CODEWITHSUNDEEP
javamavenswaggerswagger-maven-plugin
Raj
Raj

Reputation: 1148

Using Javadocs to generate Swagger document

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?

Upvotes: 29

Views: 28110

Answers (3)

dan carter
dan carter

Reputation: 4341

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

Upvotes: 3

Egemen
Egemen

Reputation: 2548

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.

Upvotes: 18

dsavickas
dsavickas

Reputation: 1560

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

Upvotes: 1

Related Questions