Generate REST API documentation

Question

Is there a way to auto-generate a ZOHO-style documentation of my Jersey Rest Services? This is one of the best REST documentations I have seen so far. I'm open to alternatives.

Swagger also looks promising but I don't see how to generate it. It seems like it needs a YAML style documentation.

Can I generate it from javadoc somehow?

I'd prefer to generate the docs via Maven.

Answer 1

You can use Swagger to document your REST API, it's not difficult to set up. There are some instructions here. To summarize:

Adding Swagger dependencies

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.0</version>
</dependency>

Setting up Swagger

Add the following to your Application class (change the values according to your needs):

@ApplicationPath("/api")
public class MyApplication extends Application {

    public MyApplication() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8080");
        beanConfig.setBasePath("/api");
        beanConfig.setResourcePackage("io.swagger.resources,com.example.project");
        beanConfig.setScan(true);
    }
}

Build your project, start your server and access http://localhost:8080/app/api/swagger.json (the URL might be different in your environment) to get the JSON which documents your API.

Setting up Swagger UI

Download Swagger UI from GitHub and copy the content from the dist folder to your web content folder. I usually create a folder called api-docs to store all Swagger UI files.

Open Swagger UI's index.html and change the URL which refers to the swagger.json:

var swaggerUi = new SwaggerUi({
    url: "http://localhost:8080/app/api/swagger.json",
    dom_id: "swagger-ui-container"
});

Access http://localhost:8080/app/api-docs (the URL might be different in your environment). The Swagger UI with your API documentation should be there.

More information

• You always can customize Swagger UI to fit your needs.

• Swagger reads JAX-RS annotations to generate the documentation. Additionally, you can use Swagger annotations to improve it.

Answer 2

You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module. First, you need to add the maven plugin to your pom file; e.g.

<plugin>
        <groupId>com.webcohesion.enunciate</groupId>
        <artifactId>enunciate-maven-plugin</artifactId>
        <version>${enunciate.version}</version>
        <executions>
           <execution>
                  <goals>
                    <goal>docs</goal>
                  </goals>
                  <configuration>
                    <configFile>enunciate.xml</configFile>
                    <docsDir>${project.build.directory}</docsDir>
                  </configuration>
           </execution>
        </executions>
</plugin>

where 'enunciate.xml' contains your project specific configurations and looks like this:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.0.0-M.3.xsd">

    <application root="/rest" />

</enunciate>

Then run mvn package and it will generate Swagger documentation files from your Javadoc.

p.s. taken from my answer here.

Answer 3

Adding swagger to jersey based services is not too complicated. See these detailed steps on how to go about it:

Hope that helps