How can I create documentation or a JSON schema from Java classes compatible with Google Gson?

Question

I am currently implementing a set of web services intended to be used by JavaScript clients and am using Google Gson for JSON serialization/deserialization. My service contracts are thus defined in Java classes. I now need a way of generating documentation of these message interfaces in a way intended to be used by JavaScript developers.

Ideally, I would like a tool along the lines of JavaDoc that generated JSON examples, JSON schemas or other Web developer friendly documentation of my types, that could easily be integrated with Maven to produce HTML based documentation for types with a certain annotation.

I can point them to the generated JavaDoc, but it will require them to understand and hunt through all private fields to work out how to format requests, and also does not take into account Gson type converters etc.

Are there any relevant tools available in this area?

Answer 1

I have used Swagger in the past. It is simple to implement, yet generates powerful API doc.

Please look at this documentation. I think this is what you are looking for.

http://petstore.swagger.wordnik.com/