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

﹏ヽ暗。殇╰゛Y 2022-06-01 05:55 200阅读 0赞

> 在阅读本文之前，您先需要了解Swagger的使用，如果您还不知道它是用来干嘛的，请先阅读[《Spring Boot中使用Swagger2构建强大的RESTful API文档》][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][https_github.com_13001260824_swagger]

## 如何使用 ##

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

### 生成AsciiDoc ###

生成AsciiDoc的方式有两种：

1.  通过Java代码来生成

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

<table style="margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; border-width:0px; font-weight:inherit; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle; line-height:1.6em"> 
 <tbody style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <tr style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <td style="padding:10px 20px 10px 0px; margin:0px; border-style:none; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle"> <pre style="overflow:auto; font-family:inherit; font-size:16px; margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; font-weight:inherit; font-style:inherit; vertical-align:baseline">&lt;dependencies&gt;
 ...

 &lt;dependency&gt;
 &lt;groupId&gt;io.github.swagger2markup&lt;/groupId&gt;
 &lt;artifactId&gt;swagger2markup&lt;/artifactId&gt;
 &lt;version&gt;1.3.1&lt;/version&gt;
 &lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;repositories&gt;
 &lt;repository&gt;
 &lt;snapshots&gt;
 &lt;enabled&gt;false&lt;/enabled&gt;
 &lt;/snapshots&gt;
 &lt;id&gt;jcenter-releases&lt;/id&gt;
 &lt;name&gt;jcenter&lt;/name&gt;
 &lt;url&gt;http://jcenter.bintray.com&lt;/url&gt;
 &lt;/repository&gt;
&lt;/repositories&gt;
</pre> </td> 
 </tr> 
 </tbody> 
</table>

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

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

*  `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目录下获得如下内容：

可以看到，这种方式在运行之后就生成出了4个不同的静态文件。

输出到单个文件

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

1.  通过Maven插件来生成

除了通过上面编写Java代码来生成的方式之外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，完全可以通过在`pom.xml`中增加如下插件来完成静态内容的生成。

<table style="margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; border-width:0px; font-weight:inherit; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle; line-height:1.6em"> 
 <tbody style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <tr style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <td style="padding:10px 20px 10px 0px; margin:0px; border-style:none; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle"> <pre style="overflow:auto; font-family:inherit; font-size:16px; margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; font-weight:inherit; font-style:inherit; vertical-align:baseline">&lt;plugin&gt;
 &lt;groupId&gt;io.github.swagger2markup&lt;/groupId&gt;
 &lt;artifactId&gt;swagger2markup-maven-plugin&lt;/artifactId&gt;
 &lt;version&gt;1.3.1&lt;/version&gt;
 &lt;configuration&gt;
 &lt;swaggerInput&gt;http://localhost:8080/v2/api-docs&lt;/swaggerInput&gt;
 &lt;outputDir&gt;src/docs/asciidoc/generated&lt;/outputDir&gt;
 &lt;config&gt;
 &lt;swagger2markup.markupLanguage&gt;ASCIIDOC&lt;/swagger2markup.markupLanguage&gt;
 &lt;/config&gt;
 &lt;/configuration&gt;
&lt;/plugin&gt;
</pre> </td> 
 </tr> 
 </tbody> 
</table>

### 生成HTML ###

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

<table style="margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; border-width:0px; font-weight:inherit; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle; line-height:1.6em"> 
 <tbody style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <tr style="margin:0px; padding:0px; border:0px; font-weight:inherit; font-style:inherit; font-family:inherit; vertical-align:baseline"> 
 <td style="padding:10px 20px 10px 0px; margin:0px; border-style:none; font-style:inherit; font-family:inherit; font-size:16px; vertical-align:middle"> <pre style="overflow:auto; font-family:inherit; font-size:16px; margin-right:0px; margin-bottom:0px; margin-left:0px; padding:0px; font-weight:inherit; font-style:inherit; vertical-align:baseline">&lt;plugin&gt;
 &lt;groupId&gt;org.asciidoctor&lt;/groupId&gt;
 &lt;artifactId&gt;asciidoctor-maven-plugin&lt;/artifactId&gt;
 &lt;version&gt;1.5.6&lt;/version&gt;
 &lt;configuration&gt;
 	 &lt;sourceDirectory&gt;src/docs/asciidoc/generated&lt;/sourceDirectory&gt;
 	 &lt;outputDirectory&gt;src/docs/asciidoc/html&lt;/outputDirectory&gt;
 	 &lt;backend&gt;html&lt;/backend&gt;
 	 &lt;sourceHighlighter&gt;coderay&lt;/sourceHighlighter&gt;
 	 &lt;attributes&gt;
 &lt;toc&gt;left&lt;/toc&gt;
 	 &lt;/attributes&gt;
 	&lt;/configuration&gt;
&lt;/plugin&gt;
</pre> </td> 
 </tr> 
 </tbody> 
</table>

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

[![swagger2markup-asciidoc.png][]][swagger2markup-asciidoc.png]

[Spring Boot_Swagger2_RESTful API]: http://blog.didispace.com/springbootswagger2/
[https_github.com_13001260824_swagger]: https://github.com/Swagger2Markup/swagger2markup
[spring-boot-starter-swagger]: https://github.com/SpringForAll/spring-boot-starter-swagger
[https_github.com_13001260824_swagger 1]: https://github.com/dyc87112/swagger-starter-demo
[swagger2markup-asciidoc.png]: /images/20220601/614bec0b71da4f7a9f57b1f16aa8bc8b.png