Spring REST API Documentation using Swagger
I am looking for a tool which could help me generate RESTful API documentation. My server is written in Java and uses Spring MVC framework. I do not have VIEWS in my server. It's a 100% RESTful service and all it does is consumes JSON and spits out JSON.
I was wondering if Swagger is compatible with Spring annotations?
Answer
There currently is not a Spring MVC swagger module available (from Wordnik at least) but in general, enabling swagger on a JVM-based REST service is pretty simple.
Swagger server support is divided into two parts--the core server and the integration with the REST service. See the Swagger github repo. Swagger core defines the document that represents the REST service, parameters, allowable values, HTTP operations, etc. The server integration wires this document to the structure of the REST framework. Wordnik uses Jersey via JAX-RS and released swagger-jaxrs to do this integration. There is also a Swagger-Play module which will be released to the Play module repository shortly.
If you want to enable swagger on another REST framework (like Spring MVC), you follow these steps:
1) Generate an API Reader to generate a com.wordnik.swagger.core.Documentation object. See the JAX-RS version as well as the one for play.
2) Create a REST endpoint which returns a JSON/XML version of the Documentation object to the client. Again, JAX-RS and play.
3) Add a filter to intercept requests to enforce resource or object-level access.
So in short, it could be put together pretty easily.