使用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生成美观的Restful API文档_第1张图片

    如上图所示,在项目中,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好多了?

使用swagger2markup和asciidoctor生成美观的Restful API文档_第2张图片

    还可以在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的地址。

使用swagger2markup和asciidoctor生成美观的Restful API文档_第3张图片

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

生成请求和响应的样例JSON

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

使用swagger2markup和asciidoctor生成美观的Restful API文档_第4张图片

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

使用swagger2markup和asciidoctor生成美观的Restful API文档_第5张图片

在文档中添加静态章节

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

== 码表

=== 性别

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

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

使用swagger2markup和asciidoctor生成美观的Restful API文档_第6张图片

参考文献

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

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

你可能感兴趣的:(实用技术)