Generating Rest API documentation using swagger or any other tool

Question

I am looking for a way to document my Rest APIs. My server is a Tomcat/Spring server and the Rest APIs are implemented using Jenkins.

Swagger seems to be a pretty cool solution but i can't figure out how i can use it with my code. I am looking for the best way to create the json swagger-ui can read - how i should do that?

Also, i would be happy to check any other good solutions for documenting Rest APIs in such environment.

Solution 1

I haven't tried swagger but you may try enunciate. It can generate documentation of JAX-RS endpoints as a part of javadoc phase. Some examples of generated documentation are available on enunciate page

Update

Project has been moved to http://enunciate.webcohesion.com/, java 8 will be supported by upcoming version 2.0.

Solution 2

To enable swagger-ui, you can use it "as-is" - from documentation:

"You can use the swagger-ui code AS-IS! No need to build or recompile--just clone this repo and use the pre-built files in the dist folder. If you like swagger-ui as-is, stop here."

So basically you would need only to place the "dist" contents in your web server, then you enter the swagger endpoint of your web service in the UI, for example: http://localhost:8080/Webservice/api-doc.json (this is the same address endpoint you have to define in your web.xml).

I suspect you have some other details misconfigured, which is easy as there are several places you have to configure Swagger. In the following I give you some details of my own setup in Swagger.

This is a snippet of the Swagger configurations on my web.xml:

<!-- // Jersey declaration -->
<servlet>
    <servlet-name>web service</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.config.property.classnames</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/Webservice</param-value>
    </init-param>
    <init-param>
        <param-name>api.version</param-name>
        <param-value>0.0.2</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
    <servlet-name>Bootstrap</servlet-name>
    <servlet-class>com.mywebservice.utils.swagger.Bootstrap</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>com.mywebservice.utils.swagger.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Bellow is a listing of the com.mywebservice.utils.swagger package, where there are several resources as presented in the Swagger documentation (which now seems to be different from when I set it up, so here it is the full list of documents):

You can find these files (or examples) in the example project from Swagger: https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs, which you should try to use as a "template" to setup your swagger. The one file I had trouble with was the ApiListingResource:

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.jaxrs.JavaApiListing;

@Path("/resources.json")
@Api("/resources")
@Produces({ "application/json"})
public class ApiListingResource extends JavaApiListing{
}

HTH.

Solution 3

If you're using JAX-RS and maven, you might consider trying MireDot as well, it's super-easy to set up.

Comments

[Erik Sapir]

I see the enunciate requires to use Maven. We don't use maven when building our application - is there a way to use enunciate without maven? Or maybe i can use maven only to generate the docs?

[ragnor]

Maven is not required, you can use Ant to invoke enunciate: enunciate.codehaus.org/executables.html

[Erik Sapir]

I can use ant also to only generate documentation from source code or i must also use ant to build the whole application?

[ragnor]

If you don't use Ant to build your project there is also command line tool to generate documentation: enunciate.codehaus.org/executables.html#command

[Erik Sapir]

Great! I will check it. Thanks!

[Erik Sapir]

Are you using ant or maven to build your app?

[Erik Sapir]

I tried to do the same, but i can't figure out how the actual json files are created

[emgsilva]

I use maven, but that should make no big difference... What do you mean by "figure out how the actual json files are create"? If you have it all configured (similar to what I have above) you should be able to access the documentation via the link on the deployed ".war" (you can also try to test in Eclipse if you use it, with Tomcat, for example). Make sure you have the swagger.api.basepath with the "endpoint" of your deployed .war, if that is different it will not work... But maybe you should give more details to try to help you further!

[Erik Sapir]

I am not using war, but generate only jar files. I am not sure what swagger.api.basepath should be. Also, did you use swagger jars or added the actual code to your project?

[Erik Sapir]

When the json files are generated? I am missing this part - something need to actually create them, no?

[emgsilva]

Aren't you developing a web service (REST API) using Jersey? If so, at a given point you will deploy it (as .war or .ear) to you can serve clients. Normally with Swagger (as I have configured) you only get the "JSON files" on the Swagger-UI (or another client) when the web service is running. Basically the web service is generating "on the fly" the "JSON files". Alternatively, and maybe this is what you are looking for, there is this project: github.com/ryankennedy/swagger-jaxrs-doclet, which aims at "generate a Swagger resource listing suitable for feeding to swagger-ui."

[Roland Tepp]

Looks nice, but the fact that I can not immediately see the pricing info for the commercial use does not really inspire much trust...