使用swagger2markup和asciidoctor生成美观的Restful API文档

    目前，大家通常都是用Swagger来编写Rest API文档，使用Swagger注解和Springfox，可以方便的从源代码生成文档，保持文档和源码一致。使用Swagger-ui工具，接口的消费方可以查看接口定义并从浏览器直接调用接口。如何实现Swagger和Spring Boot项目的结合，可以参考文章Spring Boot RESTful API Documentation With Swagger 2和Springfox的官方文档。

    但是，有时我们为其它读者提供API文档，例如尊贵的客户领导要验收工作成果，Swagger UI就显得不太正式了，而且要连接上运行Swagger UI的服务器才可以完整的查看。最近，笔者找到了工具swagger2markup和asciidoctor，结合起来使用就可以输出优美的API文档了，供大家参考。

使用Swagger2Markup Demo

    笔者尝试了多种方式后，发现结合swagger2markup和asciidoctor两个工具需要较多的配置，Swagger2Markup Demo项目已经做好了基本的配置，是一个Quick-Wins的路径。

样例程序的使用

    从GitHub上克隆Swagger2Markup Demo项目，然后导入WorkSpace。

    如上图所示，在项目中，swagger2markup和asciidoctor是在pom.xml文件中以Maven插件的形式引入的，项目已经对两个插件做了配置。在src/docs/asciidoc目录中，存放了生成最终文档的索引文件，index.adoc的内容是：

include::{generated}/overview.adoc[]
include::manual_content1.adoc[]
include::manual_content2.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::{generated}/definitions.adoc[]

    {generated}目录下的adoc文件都是swagger2markup根据swagger生成的，同时，该文件示例引入了两个静态文件manual_content1.adoc和manual_content2.adoc。

    在项目上执行mvn clean test，执行成功后，即可在target/asciidoc/html目录下找到生成的index.html文档，如下所示，是否觉得可读性比Swagger UI好多了？

    还可以在target\asciidoc\pdf目录中可以找到生成的index.pdf文档，不过当REST API文档中有中文时，生成的PDF会发生漏字的问题，无法使用。

    样例程序的原理是springfox-staticdocs从API代码的注解生成了静态的Swagger API文档swagger.json，并放在了target/swagger目录下。swagger2markup读取静态的swagger.json文件生成了asciidoctor所需的adoc文件。下面一起来看看如何使用动态的Swagger API文档。

使用动态Swagger API文档

    假设项目的动态Swagger地址是http://localhost:6060/v2/api-docs，注意在浏览器中打开应当看到一个JSON文档，而非Swagger UI。如图，将spring-swagger2markup-demo项目pom.xml文件中的swaggerInput标签中的内容改为动态Swagger的地址。

    再次执行mvn clean test，即可在target/asciidoc/html目录下找到新生成的index.html文档。

生成请求和响应的样例JSON

    Swagger UI中有一个很棒的特性，就是可以显示请求和响应的样例JSON，便于接口的消费方使用。但在样例中，生成的文档中并没有样例JSON，可以通过在swagger2markup Maven插件中增加一项swagger2markup.generatedExamplesEnabled配置来增加样例JSON，如图：

   再次执行mvn clean test，即可在target/asciidoc/html目录下找到新生成的index.html文档。可以看到生成的JSON样例：

在文档中添加静态章节

    前文中已经介绍了，样例中演示了如何在index.adoc中引入静态章节，我们可以利用这一特性添加一些Swagger没有生成的内容，作为API文档的补充，如笔者在manual_content1.adoc中定义了一段码表内容：

== 码表

=== 性别

[options="header", cols=".^2,.^14"]
|===
|代码|含义
|**M**|男
|**F**|女
|===

     执行mvn clean test后，在文档中添加了以下的内容：

参考文献

1. http://swagger2markup.github.io/swagger2markup/1.3.3/

2. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference