Is there a recommended way to document JSON payload structures outside of HTTP request bodies

[davidgoate]

Currently, I document a valid sample request using the HTTP request body snippet.

But, I often find myself writing manual ASCIIDOC tables in the documentation prior to a sample request/response that documents:

1. the JSON property names
2. The JSON type (string, integer, boolean)
3. The associated validation rules, e.g. not null, length <200 chars, must match pattern xyz. - I'm still not quite sure how Bean Validation API support #42 works - I need to brush up on my reading of the docs related to this feature

When the developer reads the docs of the sample http request it's very useful to see one example of a valid payload. it should help to answer "what are the property names" and "what are the data types". But this might not always be so clear, e.g. if the sample request sends 5, does the endpoint allow floating point numbers 5.0? Are there any fields which were missing from the request because perhaps they were null and the Jackson serialiser is configured to not send null values (arguably a bad test)?

To solve the first and second problem, is there any potential for a module which would use some sort of jackson introspection to discover all the object graph properties and their associates type (mapped to JSON data types) .

Obviously my current manual tables need to be maintained by hand and are cumbersome/error prone.

[wilkinsona]

This sounds a lot like #277 to me. Do you agree @davidgoate?

[davidgoate]

@wilkinsona looks very similar - although the lazy part of me was hoping more for something where I can point the documentation generator at a class file, e.g. MyDto.class and it'll automatically discover the fields, their types and validation rules - rather than me writing Java code to manually do this. Certainly a better approach than my current one though 👍

[wilkinsona]

I am, generally speaking, not a fan of introspecting a DTO to discover fields and types. It takes any DTO to JSON conversion out of the equation and, if the introspection doesn't use the exact same conversion that your app does at runtime, can lead to inaccurate documentation.

The closest REST Docs gets to this sort of introspection is in ConstraintDescriptions. It'll introspect the constraints on a given class, but you're still required to match those up with the corresponding JSON field.

I'll close this one as a duplicate of #277. Please feel free to comment on that issue. I don't want to go down the introspection route, but I'm definitely open to any other suggestions that would make the feature useful to you.