The extended WADL of Jersey has a nice feature for XML documentation, where you can say:
@response.representation.200.example {_at_link Examples#MY_SAMPLE_OBJECT}
The WADL generator will actually marshal the MY_SAMPLE_OBJECT to XML for the documentation. That way the documentation reflects the REAL way that object would be represented. Awesome!
Unfortunately, all of my services produce JSON. In JSON, the example is even more important because there is no equivalent of a schema for JSON. Is there anything similar available for JSON? Has anyone written anything custom that I could look at as an example?