使用Swagger2Markup实现API文档的静态部署（一）：AsciiDoc

在阅读本文以前，您先须要了解Swagger的使用，若是您还不知道它是用来干吗的，请先阅读 《Spring Boot中使用Swagger2构建强大的RESTful API文档》一文。

前言

在学会了如何使用Swagger以后，咱们已经可以轻松地为Spring MVC的Web项目自动构建出API文档了。可是，如前文方式构建的文档必须经过在项目中整合swagger-ui、或使用单独部署的swagger-ui和/v2/api-docs返回的配置信息才能展示出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，好比：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Ma...

如何使用

在使用Swagger2Markup以前，咱们先须要准备一个使用了Swagger的Web项目，能够是直接使用Swagger2的项目，也能够是使用了spring-boot-starter-swagger的项目，好比我仓库中的：https://github.com/dyc87112/s... ，下面就来看看如何使用Swagger2Markup来建立AsciiDoc。

生成AsciiDoc

生成AsciiDoc的方式有两种：

1. 经过Java代码来生成

第一步：编辑pom.xml增长须要使用的相关依赖和仓库

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
</dependencies>

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

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

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

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        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"));
    }

}

以上代码内容很简单，大体说明几个关键内容：

• MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC以外，还有MARKDOWN和CONFLUENCE_MARKUP
• from(new URL("http://localhost:8080/v2/api-docs")：指定了生成静态部署文档的源头配置，能够是这样的URL形式，也能够是符合Swagger规范的String类型或者从文件中读取的流。若是是对当前使用的Swagger项目，咱们经过使用访问本地Swagger接口的方式，若是是从外部获取的Swagger文档配置文件，就能够经过字符串或读文件的方式
• toFolder(Paths.get("src/docs/asciidoc/generated")：指定最终生成文件的具体目录位置

在执行了上面的测试用例以后，咱们就能在当前项目的src目录下得到以下内容：

src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc

能够看到，这种方式在运行以后就生成出了4个不一样的静态文件。

输出到单个文件

若是不想分割结果文件，也能够经过替换toFolder(Paths.get("src/docs/asciidoc/generated")为toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样能够最终生成html的也是单一的。

1. 经过Maven插件来生成

除了经过上面编写Java代码来生成的方式以外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，彻底能够经过在pom.xml中增长以下插件来完成静态内容的生成。

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

生成HTML

好了，完成了从Swagger文档配置文件到AsciiDoc的源文件转换以后，就是如何将AsciiDoc转换成可部署的HTML内容了。这里继续在上面的工程基础上，引入一个Maven插件来完成。

<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>

经过上面的配置，执行该插件的asciidoctor:process-asciidoc命令以后，就能在src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成以后，能够直接经过浏览器来看查看，你就能看到相似下图的静态部署结果：

是否是感受似曾相识呢？是的，Spring Cloud的E版以前的文档也是这样的！！！

本文首发： http://blog.didispace.com/swa...