How to Generate Static API Docs with Swagger2Markup for Spring Boot

Introduction

After introducing Swagger basics and usage details, you may need to provide static API documentation to external parties without running the Swagger UI. This article shows how to quickly generate such static docs using Swagger2Markup.

Swagger2Markup Overview

Swagger2Markup is an open‑source project on GitHub that converts Swagger‑generated specifications into formats like AsciiDoc, Markdown, and Confluence markup for easy static deployment.

How to Use

Prepare a Spring Boot project that already integrates Swagger (e.g., the chapter2-2 module of the SpringBoot‑Learning demo). Then choose one of the following methods to generate documentation.

Generate AsciiDoc

Via Java code

Step 1: Add the Swagger2Markup dependency to pom.xml (scope set to test so it is not packaged).

<dependencies>
    ...
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <snapshots><enabled>false</enabled></snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

Step 2: Write a JUnit test that invokes Swagger2Markup to convert the Swagger JSON endpoint.

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

    @Test
    public void generateAsciiDocs() throws Exception {
        URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
        Path outputDirectory = Paths.get("src/docs/asciidoc/generated");
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();
        Swagger2MarkupConverter.from(remoteSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }
}

The test produces four AsciiDoc files ( definitions.adoc, overview.adoc, paths.adoc, security.adoc) under src/docs/asciidoc/generated. To combine them into a single file, replace toFolder(...) with toFile(Paths.get("src/docs/asciidoc/generated/all")).

Via Maven plugin

Add the following plugin configuration to pom.xml:

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated-by-plugin</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

Start the Spring Boot application, then run the plugin (e.g., mvn swagger2markup:convert) to obtain the same AsciiDoc files.

Generate HTML

After obtaining AsciiDoc files, use the Asciidoctor Maven plugin to convert them to 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>

Running asciidoctor:process-asciidoc generates deployable HTML files in src/docs/asciidoc/html. The result looks like the screenshot below:

Markdown and Confluence Support

To generate Markdown or Confluence markup, simply change the withMarkupLanguage setting in the Java code or the swagger2markup.markupLanguage property in the Maven plugin.

Generate Markdown

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/markdown/generated");
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.MARKDOWN)
        .build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
        .withConfig(config)
        .build()
        .toFolder(outputDirectory);

Generate Confluence markup

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/confluence/generated");
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
        .build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
        .withConfig(config)
        .build()
        .toFolder(outputDirectory);

After execution, the project contains separate directories for Markdown ( src/docs/markdown/generated) and Confluence ( src/docs/confluence/generated) with the corresponding files.

Deploying Markdown

Markdown files can be published using static‑site generators such as Hexo or Jekyll, or SaaS documentation platforms.

Deploying Confluence

In Confluence, create a new page, choose the {}Markup macro, select Confluence Wiki, and paste the generated .txt content. The preview will render the API documentation correctly.

Code Example Repository

The complete example project is available at:

GitHub: https://github.com/dyc87112/SpringBoot-Learning/tree/2.x

Gitee: https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

References

Swagger2Markup GitHub repository

Swagger2Markup AsciiDoc tutorial

Swagger2Markup Markdown & Confluence tutorial