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