Spring REST API Documentation using Swagger [close

Question

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

Want to improve this question? Update the question so it's on-topic for Stack Overflow.

Closed 2 years ago.

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 1

Swagger 2.0 is the latest version of Swagger.

There are different variations of Swagger now available for differing needs.

io.swagger is the package for swagger libraries and you need separate spring jars to couple it with Spring. This is version 2 of swagger.

io.springfox is Springfox Swagger2, wherein swagger comes integrated with Spring.

com.mangofactory is swagger integrated with Spring Web MVC framework.

Answer 2

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.

Answer 3

Another implementation of Swagger for Spring MVC is swagger4spring-web.

It's similar to Swagger-SpringMVC and supports all Swagger annotations and generates JSON schema for return types and parameters. It also works without swagger annotations.

Answer 4

If you are only after generating an interactive API document (without the need for wiki style collaboration), I/O Docs would be a better solution requires much less effort to set up, use and customise, IMHO.

It's running on nodejs and Redis. You only need to write a JSON schema of your API and it generates a HTML/JS site that describes your API and lets developers to play with it live from their browser.

I plan to host my API on my server (as requiring anyone to install 2 other softwares just to view the API would be crazy) but the JSON schema itself already has a nice readable and compact structure which I think would be sufficient for collaboration with other programmers. It's a small project.

There is a similar question you may want to check out.

Answer 5

There is a Swagger-SpringMVC implementation in progress here and examples here.

The spec v1.2 is fully implemented and supported (ie., models are generated, with full support for generics), and it's under active development.