I want to build the Swagger documentation for an existing set of RESTful APIs. I have the following requirement:
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?
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.