Diffa Diffa

The doc gen should generate example JSON for POST requests as well as GET requests. ATM the RestGen only jsonifies the return type of the annotated REST API, not any POST parameters. This means that POST requests are effectively not-documented.

The HTTP content type should be documented as well.

In addition to this, the examples need to be made more comprehensive:

• RangeCategoryDescriptor should have all of its fields set.
• We need to include examples of all subtypes of CategoryDescriptor
• All of the fields of an Endpoint need example values
• Where does the @type field in a RangeCategoryDescriptor come from when it's rendered?
• The id field of RangeCategoryDescriptor should not feature in the JSON as this a surrogate DB key

Is it possible to add examples keyed by the actual method you are trying to document. ATM the examples are keyed by object type, which makes the examples reuseable, but in the case of {GET,POST} config/xml, it might be feasible to maintain an instance of the XML variant of DiffaConfig (see DiffaConfigReaderWriterTest) that is keyed on that method. When this is invoked in the RestGen, the example field could get populated with that XML.

If this is easy enough to do, having a resource level description on the main REST doc page would be nice. If this increases the scope of this ticket too much, we should break it out into another ticket.