Keywords: Swagger | PDF | Springfox | Swagger2Markup
Abstract: This article explores the optimal approach to generate static PDF documentation from Swagger API specifications for offline use and easy sharing. Focusing on the integration of Springfox and Swagger2Markup in a Spring Boot project, it provides step-by-step implementation details, code examples, and compares it with alternative methods such as browser printing and online tools, aiding developers in efficient documentation management.
Introduction
Swagger UI is widely used to display REST web services documentation, but it requires server access for online viewing. For scenarios where offline work or easy sharing with stakeholders is needed, generating a static PDF from Swagger documentation becomes essential. This article addresses this challenge by presenting a robust method using Springfox and Swagger2Markup.
Integrating Springfox for Swagger Documentation
Springfox is a library that automates the generation of Swagger documentation for Spring-based applications. To integrate it, add the following dependencies to your pom.xml or build.gradle file.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>Then, configure a Swagger Docket in your Spring Boot application.
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build();
}
}This setup enables Swagger UI at /swagger-ui.html.
Generating PDF with Swagger2Markup
Swagger2Markup converts Swagger JSON or YAML specifications into AsciiDoc, which can then be rendered to PDF using tools like Asciidoctor. Add the Swagger2Markup dependency.
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-spring-restdocs</artifactId>
<version>1.3.3</version>
</dependency>Create a utility class to generate the documentation.
import io.github.swagger2markup.Swagger2MarkupConverter;
import java.nio.file.Paths;
public class PdfGenerator {
public static void generatePdf(String swaggerJsonUrl, String outputDir) {
Swagger2MarkupConverter.from(swaggerJsonUrl)
.build()
.toFolder(Paths.get(outputDir));
// Then use Asciidoctor to convert AsciiDoc to PDF
}
}After generating AsciiDoc files, use Asciidoctor or a similar tool to produce the final PDF.
Alternative Methods
For quick solutions, browser printing can be used by hiding the editor pane and printing to PDF, as suggested in Answer 1. Alternatively, online tools like SwDoc (Answer 2) automate the process without local setup.
Conclusion
The integration of Springfox and Swagger2Markup provides a scalable and automated way to generate PDF documentation from Swagger APIs, suitable for production environments. While browser printing and online tools offer convenience, this method ensures consistency and customization. Choose based on your project requirements.