Preface: this is a rather old article from my old blog, just updated with code blocks and highlighting that Wordpress did not have at the time. I expect that the configuration has changed since and there may be libraries and tools that automate this process.

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.

Hence I was very happy to find and implement automatic documentation using the Swagger JaxRs maven build plugin. Configuring the plugin can be done in three simple steps. Just note that I am using swagger 2.1.0, and you probably should 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 part:

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

Wrapping it up

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!)