Swagger API文档生成离线HTML文档

引言

在学会了使用 Swagger 之后，我们能够轻松地为 SpringBoot 项目自动构建API文档。但是，我们构建的文档需要在项目中整合 swagger-ui 或使用单独部署的 swagger-ui 和 /v2/api-docs 返回的配置信息才能展现出 API 文档。这里我们将在使用 Swagger 的基础上，介绍一种生成静态 API 文档的方法，以便于构建更轻量部署和使用的 API 文档。

Swagger2Markup

Swagger2Markup 是 Github 上的开源项目。Swagger2Markup 可以将 Swagger 生成的文档转化成流行的格式以便于独立部署和使用，如：Markdown、Confluence、AsciiDoc。

GitHub：https://github.com/Swagger2Markup/swagger2markup

生成AsciiDoc（Java代码生成）

一、编辑 pom.xml 增加需要使用的相关依赖、仓库和插件

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>
<!-- 引用以下两个包是防止生成过程中出现找不到类的异常 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.5.16</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.16</version>
</dependency>
<!--测试依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<repositories>
    <repository>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>
<build>
    <plugins>
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.6</version>
            <configuration>
                <!-- asciidoc文件目录 -->
                <sourceDirectory>./docs</sourceDirectory>
                <!-- 生成HTML的路径 -->
                <outputDirectory>./html</outputDirectory>
                <backend>html</backend>
                <sourceHighlighter>coderay</sourceHighlighter>
                <attributes>
                    <!-- 导航栏在左侧 -->
                    <toc>left</toc>
                    <!-- 显示菜单层级数 -->
                    <toclevels>3</toclevels>
                    <!-- 自动打数字序号 -->
                    <sectnums>ture</sectnums>
                </attributes>
            </configuration>
        </plugin>
    </plugins>
</build>

二、编写一个单元测试用例来生成执行生成文档的代码

import java.net.URL;
import java.nio.file.Paths;
import org.junit.Test;
import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;

public class Swagger2MarkupTest {
    /**
     * 生成AsciiDocs格式文档
     * 
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        // 输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples()
                .withoutInlineSchema().build();

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

    /**
     * 生成Markdown格式文档
     * 
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        // 输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples()
                .withoutInlineSchema().build();

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

    /**
     * 生成Confluence格式文档
     * 
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        // 输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP).withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples().withoutInlineSchema().build();

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

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * 
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        // 输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples()
                .withoutInlineSchema().build();

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

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * 
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        // 输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples()
                .withoutInlineSchema().build();

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

以上代码说明了几个关键内容：

MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP。
from(new URL("http://localhost:8080/v2/api-docs")：指定了生成静态文档的数据源配置。
toFolder(Paths.get("src/docs/asciidoc/generated")：指定了最终生成文件的目录位置。如果不想分割结果文件，也可以改成toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个文件中，这样最终也只会生成一个html文件。
在执行测试用例之后【执行前需要运行主服务，也就是接口服务】，就能在当前项目的目录下获得如下内容：