Spring REST API Documentation using Swagger

Question

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?

Solution 1

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.

Solution 2

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.

Solution 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.

Solution 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.

Solution 5

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.

View more solutions

Comments

[tbruyelle]

Is it possible to create a pure java based module ?

[Marty Pitt]

A SpringMVC module for Swagger now exists here: github.com/martypitt/swagger-springmvc

[stephen.hanson]

It's a couple years later. The example project you listed is using Swagger 0.7.0 (current version at this time is 0.8.3). Can you confirm that the example project is still relevant? I'm having trouble configuring my project.

[Dilip Krishnan]

@steve.hanson 0.8.4 has been released and it has updated links to the the sample demo in the ReadMe. Also the configuration has been vastly simplified

[Stephan]

Can you please commit swagger tag? See here: stackoverflow.com/documentation/swagger/commit