Using Javadocs to generate Swagger document

Question

I want to build the Swagger documentation for an existing set of RESTful APIs. I have the following requirement:

Generate Swagger Doc offline (I used http://kongchen.github.io/swagger-maven-plugin/). This plugin helps me to generate the Swagger documentation during compile time.
Reading the existing Javadoc so that they can be used in the Swagger documentation.

So far using the above plugin I was able to achieve point no 1. So for an existing REST method:

 /**
 * <p>
 * Gets the {@link DisplayPreferenceModel} with the name as provided in the parameter. The preference with the given name defined at the tenant or master level is returned.
 * This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required.
 * </p>
 * @param preferenceName
 *            - The name of the preference.
 * @return {@link DisplayPreferenceModel}
 */
@RequestMapping(method = RequestMethod.GET, value = "/preferences/{preferenceName}")
@ApiOperation(value = "This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required", 
                        notes = "No Notes please", response = DisplayPreferenceModel.class)
@ApiResponses(value = { 
                        @ApiResponse(code = 400, message = "Invalid preferenceName supplied"), 
                        @ApiResponse(code = 404, message = "Display Preference Not Found")
                      }
            )
public DisplayPreferenceModel getDisplayPreference( @PathVariable("preferenceName") final String preferenceName ) {
}

I was able to generate the Swagger documentation. The usage of @ApiOperation & @ApiResponses makes my documentation looks great.

However, my question is can I use the Javadocs instead of making every developer to create @ApiOperation & @ApiResponses so that it saves time for my team?

how to generate this docs @raj? my project is maven based i ahve added Api notation, ApiResonses notation as well but how can i generate the docs any help? — Irfan Nasim
I used 'swagger-springmvc' v1.0.2. Then I created a CustomSwaggerConfig class that had the '@Configuration' & '@EnableSwagger'. And in applicationContext.xml I referenced the CustomSwaggerConfig. — Raj
Sorry buddy, can't help you much on this. Our project uses Spring libraries and therefore we use the 'swagger-springmvc' — Raj

Egemen Egemen · Accepted Answer · 2015-11-12T09:00:07

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 compile and it will generate Swagger documentation files from your Javadoc.

Using Javadocs to generate Swagger document

2 Answers