Generate Lightweight Static API Docs with Swagger2Markup in Spring Boot

Introduction

After learning how to use Swagger to automatically generate API documentation for a Spring MVC project, you may want a lighter, static deployment. Swagger2Markup can convert the Swagger JSON into AsciiDoc, Markdown or Confluence formats, which can then be turned into static HTML.

Swagger2Markup Overview

Swagger2Markup is an open‑source tool on GitHub that transforms the output of Swagger (the /v2/api-docs endpoint) into several markup languages. The project URL is https://github.com/Swagger2Markup/swagger2markup.

Adding the Maven Dependency

In a Spring Boot project that already includes spring-boot-starter-swagger, add the following dependency to pom.xml:

<dependencies>
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
    <repositories>
        <repository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots><enabled>false</enabled></snapshots>
        </repository>
    </repositories>
</dependencies>

Write a Test to Generate AsciiDoc

Create a JUnit test that builds a Swagger2MarkupConfig and runs the converter:

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }
}

Running this test creates a set of AsciiDoc files under src/docs/asciidoc/generated, such as definitions.adoc, overview.adoc, paths.adoc, and security.adoc. If you prefer a single file, replace toFolder(...) with toFile(Paths.get("src/docs/asciidoc/generated/all.adoc")).

Generate HTML with Asciidoctor Maven Plugin

Add the Asciidoctor plugin to pom.xml to convert the generated AsciiDoc into HTML:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
</plugin>

Execute mvn asciidoctor:process-asciidoc. The HTML files appear in src/docs/asciidoc/html. Opening them in a browser shows a fully static API documentation site, as illustrated below.

Summary

This approach lets you keep the Swagger UI for development while providing a lightweight, static set of HTML pages for production or offline use, without needing a running Spring Boot instance.