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

在阅读本文之前，您先需要了解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/13001260824/swagger

如何使用

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

生成AsciiDoc

生成AsciiDoc的方式有两种：

1. 通过Java代码来生成

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

<dependencies> ... <dependency> <groupId>io.github.swagger2markupgroupId> <artifactId>swagger2markupartifactId> <version>1.3.1version> dependency> dependencies> <repositories> <repository> <snapshots> <enabled>falseenabled> snapshots> <id>jcenter-releasesid> <name>jcentername> <url>http://jcenter.bintray.comurl> 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.swagger2markupgroupId> <artifactId>swagger2markup-maven-pluginartifactId> <version>1.3.1version> <configuration> <swaggerInput>http://localhost:8080/v2/api-docsswaggerInput> <outputDir>src/docs/asciidoc/generatedoutputDir> <config> <swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage> config> configuration> plugin>

生成HTML

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

<plugin> <groupId>org.asciidoctorgroupId> <artifactId>asciidoctor-maven-pluginartifactId> <version>1.5.6version> <configuration> <sourceDirectory>src/docs/asciidoc/generatedsourceDirectory> <outputDirectory>src/docs/asciidoc/htmloutputDirectory> <backend>htmlbackend> <sourceHighlighter>coderaysourceHighlighter> <attributes> <toc>lefttoc> attributes> configuration> plugin>

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