1. Overview
In this tutorial, we'll get to know different ways of generating a PDF file from Swagger API documentation. To get familiar with Swagger, refer to our tutorial for setting up Swagger 2 with a Spring REST API.
2. Generate PDF with Maven Plugins
The first solution for generating a PDF file from Swagger API documentation is based on a set of Maven plugins. With this approach, we'll get the PDF file upon building a Java project.
The steps for producing the desired PDF file include applying several plugins in a specific order during a Maven build. The plugins should be configured to pick the resources and propagate the outputs from the previous phases as the inputs of the next phase. So, let's see how each of them works.
2.1. The swagger-maven-plugin Plugin
The first plugin we'll use is swagger-maven-plugin. This plugin produces the swagger.json file for our REST API:
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.3</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>false</springmvc>
<locations>com.baeldung.swagger2pdf.controller.UserController</locations>
<basePath>/api</basePath>
<info>
<title>DEMO REST API</title>
<description>A simple DEMO project for REST API documentation</description>
<version>v1</version>
</info>
<swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
<attachSwaggerArtifact>true</attachSwaggerArtifact>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
We need to point to the locations of our API and define the phase in the build process during which the plugin produces the swagger.json file. Here, in the execution tag, we've specified that it should do this during the package phase.
2.2. The swagger2markup-maven-plugin Plugin
The second plugin we need is the swagger2markup-maven-plugin. It takes the swagger.json output of the previous plugin as its input to produce Asciidoc:
<plugin>
<groupId>io.github.robwin</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>0.9.3</version>
<configuration>
<inputDirectory>${project.build.directory}/api</inputDirectory>
<outputDirectory>${generated.asciidoc.directory}</outputDirectory>
<markupLanguage>asciidoc</markupLanguage>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>process-swagger</goal>
</goals>
</execution>
</executions>
</plugin>
Here, we specify the inputDirectory and the outputDirectory tags. Again, we'll define package as the build phase for generating the Asciidoc for our REST API.
2.3. The asciidoctor-maven-plugin Plugin
The third and final plugin we'll use is the asciidoctor-maven-plugin. As the last of the three plugins, this one produces a PDF file from Asciidoc:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.2.1</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.6.0</version>
</dependency>
</dependencies>
<configuration>
<sourceDirectory>${project.build.outputDirectory}/../asciidoc</sourceDirectory>
<sourceDocumentName>overview.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>2</toclevels>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
</configuration>
<executions>
<execution>
<id>asciidoc-to-pdf</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${project.build.outputDirectory}/api/pdf</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
Basically, we provide the location where the Asciidoc was generated during the previous phase. Then, we define a location for it to generate the PDF documentation and specify the phase during which it should generate the PDF. Once again, we're using the package phase.
3. Generate PDF using SwDoc
Swagger to PDF is an online tool, available at swdoc.org, that generates the API documentation in a PDF file using the provided swagger.json specification. It relies on the Swagger2Markup converter and AsciiDoctor.
The principles are similar to those in the previous solution. First, Swagger2Markup converts swagger.json to AsciiDoc files. Then, Asciidoctor parses those files into a document model and converts them to the PDF file.
The solution is easy to use and is a good choice if we already have our Swagger 2 API document.
We can generate the PDF in two ways:
- providing a URL to our swagger.json file
- pasting the contents of our swagger.json file into the tool's text box
We'll use the PetStore API doc publicly available on Swagger.
For our purpose, we'll copy the JSON file and paste it into the text box:
Then, after we click the “Generate” button, we'll get the documentation in PDF format:
4. Conclusion
In this short tutorial, we've discussed two ways to generate PDF from Swagger API documentation.
The first approach relies on Maven plugins. We can use three plugins and generate the REST API documentation while building the application.
The second solution describes how to generate PDF documents using the SwDoc online tool. We can either generate the documentation from the link to our swagger.json or paste the JSON file contents into the tool.
As always, the code for these examples is available over on GitHub.
res – REST (eBook) (cat=REST)
