Writing a good API is often not enough for the clients that will need to use it. Even with the greatest improvements provided by HATEOAS, API users need a more human readable way to understand the meaning of an API and how to use it. Moreover, there is no way to document flows of executions, i.e. the sequence of API methods to call to perform a task.
JSONDoc's goal is to provide an easy and fast way to do that while coding your API.
What is JSONDoc
JSONDoc is a java library useful to build the documentation of your RESTful services.
- It is framework agnostic, meaning that you can use the jsondoc-core module with any MVC framework
- It has a Spring MVC module useful if your application already uses spring-mvc and a starter for Spring Boot
- It has a UI module useful to display the generated documentation and that also includes a playground to test API methods
- It is very light: less than 250 Kb!
How does it work?
The steps are the following:
- Declare the modules you need in your pom file
- Annotate your API, objects with the JSONDoc annotations and create API flows (see the annotation page, the how to pages and the examples page for more info)
- Expose your documentation with the UI jsondoc module or with a custom viewer
JSONDoc has a dependency to Google reflections library