Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:

>> GET ACCESS NOW

November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:

>> GET ACCESS NOW

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

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:

swagger to pdf 1

 

Then, after we click the “Generate” button, we'll get the documentation in PDF format:

swagger to pdf 2

 

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.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:

>> GET ACCESS NOW

REST footer banner
Comments are closed on this article!