Automatic Swagger integration for Dropwizard using Maven

A few projects I have worked on have looked at using Swagger to document the APIs. Unfortunately, the recommended way to achieve this involves adding a number of annotations to the endpoints and JSON representations which I feel clutter the codebase. I have never been happy with this, as in my opinion it is simply shifting the work from a wiki to some annoitations and is liable to the same problem — developers forget to update the annotations/documentation.

Note I have ported this article to itazura.io and added code highlighting; however,  the content is mostly the same.

Hence I was very happy to find and implement automatic documentation using the Swagger JaxRs maven build plugin.

Integrating the plugin can be done in three simple steps. Just note that I am using swagger 2.1.0, and you way wish to use the latest version.

1. Add the plugin to your maven build (there are instructions for gradle).

2. Add the assets in your dropwizard application.

3. Import the swagger-ui files to into your project and amend a single line to point at your service definition.

Integrating the Plugin
So the first job you need to do is add the following to your maven pom’s build section. Obviously you need to remove the “build” and “plugins” sections if you already have them in your pom.

<build>
<plugins>
<!-- Swagger Doclet -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<executions>
<execution>
<id>generate-service-docs</id>
<phase>generate-resources</phase>
<configuration>
<doclet>com.carma.swagger.doclet.ServiceDoclet</doclet>
<docletArtifact>
<groupId>com.carma</groupId>
<artifactId>swagger-doclet</artifactId>
<version>1.1.1</version>
</docletArtifact>
<reportOutputDirectory>${project.build.outputDirectory}</reportOutputDirectory>
<useStandardDocletOptions>false</useStandardDocletOptions>
<additionalparam>-apiVersion 1 -docBasePath /apidocs -apiBasePath / -swaggerUiPath ../../../src/main/resources/swagger-ui-2.1.0</additionalparam>
</configuration>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>


Just take note of the following field:

<additionalparam>-apiVersion 1 -docBasePath /apidocs -apiBasePath / -swaggerUiPath ../../../src/main/resources/swagger-ui-2.1.3</additionalparam>


• /apidocs is the location of the documention resource.
• ../../../src/main/resources/swagger-ui-2.1.0 — is the location of swagger-ui. I have it pointing to the standard resources directory, as that’s where I will place swagger-ui.

Register the Assert Bundle

First double check you are already importing dropwizard-assets in your dependencies. It should look something like this:

<dependency>
    <groupId>io.dropwizard</groupId>
    <artifactId>dropwizard-assets</artifactId>
    <version>${dropwizard.version}</version>
</dependency>

Now you can add the assets bundle within your main application class. All you need to do is add the bundle in the initialize method of your main application, like so:

@Override
public void initialize(Bootstrap bootstrap) {
// Other init code
bootstrap.addBundle(new AssetsBundle("/apidocs", "/apidocs", "index.html"));
}


Things to note here:

• /apidocs is the location of the documentation endpoint. This is the same as the value in the additionalparams section of the maven plugin.
• index.html  You shouldn’t need to change this. This is the html file that loads when you hit the resource and is provided by swagger-ui.

Importing the Swagger UI Resources

Download the latest version of Swagger (I’ve tested this setup against 2.1.0 and 2.1.3) from the Swagger-UI GitHub. You’re only interested in the dist folder, so extract the zip to a temporary directory and delete everything except for the dist folder.

In the dist folder you need to open index.html to amend the swagger service definition location. By default swagger will be pointing to the ‘petstore example’, which isn’t very useful for us! This should be located on line 36 and will look like this:

url = "http://petstore.swagger.io/v2/swagger.json";

Amend this to service.json and it will be pointing at the json schema generated by the plugin.

url = "service.json";

The next step is very simple. Create a folder in resources named swagger-ui-<version> so in my case: src/main/resources/swagger-2.1.0 Now simply move the contents of the dist folder into this newly created directory.

Testing the Setup

Now everything should be completed. Simply build your maven project (mvn clean package) and start your application as usual. The documentation should be located at <your application>/apidocs/. So if you were using the default Dropwizard ports try: localhost:8080/apidocs/  (Note the final slash is important!)