Swagger使用（二）—— 利用swagger2markup生成离线的html和pdf接口文档

上一篇：Swagger使用（一）—— Springboot2.0与Swagger2整合生成在线接口文档（支持多文件数组上传）

        当我们的项目中集成了Swagger，开发时一般只会使用在线文档，但当接口开发完成之后，我们就需要提供一份给接口调用人参考的接口文档，比如html、pdf、word等格式的接口文档。怎么生成这样的文档呢？有一个Github开源项目swagger2markup已经帮我们实现了这个功能，我们拿来用就可以了。大概过程是，首先通过调用本地接口获取项目中描述接口的json数据，然后swagger2markup利用swagger.json生成adoc文档，然后asciidoctor再通过adoc文档生成对应的html和pdf文档。下面我们来看一下具体的实现过程：

目录

一、获取项目中用Swagger描述的接口json数据

二、生成adoc文档和生成html或pdf的配置详细步骤

1、下载swagger2markup项目

2、复制该项目src目录下的docs目录到我们自己的src目录中

3、复制swagger2markup项目pom文件中的属性和仓库配置

4、复制swagger2markup项目pom文件中的插件配置

5、自己项目中的swagger依赖记得配置

6、在${project.build.directory}目录下创建swagger目录并将swagger.json文件放进来

三、生成html或pdf文档

四、解决生成的pdf文档中的乱码问题

---

一、获取项目中用Swagger描述的接口json数据

访问地址：http://localhost:8080/v2/api-docs

在浏览器右键点击另存为swagger.json文件，当然你也可以写个程序从这个接口获取到数据后自动生成json文件。

二、生成adoc文档和生成html或pdf的配置详细步骤

1、下载swagger2markup项目

swagger2markup项目地址：https://github.com/Swagger2Markup/swagger2markup

点击下载将这个项目下载下来，里面有些文件我们需要用到。

2、复制该项目src目录下的docs目录到我们自己的src目录中

我们需要用到这个目录下的三个文件，其实只需要一个index.adoc，其他两个可以删掉，但删掉之后index.adoc中的include::manual_content1.adoc[] include::manual_content2.adoc[]也要删掉。这里暂时先不管它，直接复制过来即可。

 

3、复制swagger2markup项目pom文件中的属性和仓库配置

 

4、复制swagger2markup项目pom文件中的插件配置

有两个插件配置需要复制过来，一个是生成ascciidoc文档的，一个是生成html或pdf文档的，全部复制过来放到自己项目中的pom文件中，什么都不用改。

 

5、自己项目中的swagger依赖记得配置

 

6、在${project.build.directory}目录下创建swagger目录并将swagger.json文件放进来

 

三、生成html或pdf文档

所有配置完成后，直接在根目录下使用maven test命令，或者使用Eclipse、IDEA工具执行maven test命令，BUILD SUCDESS之后我们可以在target目录下面看到生成的asccidoc目录，里面有我们需要的html或pdf文件。

四、解决生成的pdf文档中的乱码问题

通过上面的方法生成的html文档编码是没问题的，只是pdf文档中有些地方会有乱码，如果直接拿给别人看肯定是不行的，所以我们需要解决这个乱码问题。

请参考：Swagger使用（三）—— 解决swagger2markup生成的离线pdf接口文档中的乱码问题