Generating Rest API documentation using swagger or any other tool

问题

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.

回答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.

回答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.