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

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

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

目录

一、获取项目中用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

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第1张图片

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

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第2张图片

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第3张图片

 

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第4张图片

 

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

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第5张图片

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第6张图片

 

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第7张图片

 

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第8张图片

 

三、生成html或pdf文档

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

Swagger使用(二)—— 利用swagger2markup生成离线的html和pdf接口文档_第9张图片

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

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

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

你可能感兴趣的:(Swagger)