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:

1. 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.
2. 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?

Ghost

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? – Possessed

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. – Ghost

i dont have spring i am just with maven, struts – Possessed

Sorry buddy, can't help you much on this. Our project uses Spring libraries and therefore we use the 'swagger-springmvc' – Ghost

Answer 1

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.

Pulsifer

This works fantastically even without any configuration specified. Just a side note, when you use the 'docs' goal it generates on mvn compile, not mvn package. mvn package is for the 'assemble' goal which is different.Also make sure you read up on which modules you need, otherwise it will generate a ton of stuff you don't need like clients for other languages. – Rollerskate

Can this be combined with swagger.json from Springfox? – Erena

Answer 2

SpringDoc now supports generating swagger documentation from your JavaDoc, saving you from endless cut-n-paste in your models.

https://github.com/springdoc/springdoc-openapi/issues/38 https://github.com/springdoc/springdoc-openapi-maven-plugin

Bk

Answer 3

There seems to be javadoc doclet for generating JSON Swagger resource listing: https://github.com/teamcarma/swagger-jaxrs-doclet

Urushiol