导出swagger2离线API文档

前提

我的项目需要生成API文档给前端进行联调,而由于特殊原因需要生成离线文档,而项目中用到的是swagger2.x.x的版本

生成在线文档

首先通过配置swagger,启动项目.通过项目地址+/swagger-ui.html访问生成的在线文档如图所示

页面中是没有导出功能的,而标记的链接是该api文档的json地址.

下载 Swagger2Markup CLI

我们需要把json转换成一个AsciiDoc文件,那么就需要通过Swagger2markup CLI来实现

swagger2markup是一个Java库，用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown。但是这种方式进行swagger to markup的转换要编码初始化，做一堆事情，侵入性较大。

swagger2markup-cli 是一种将 swagger json文件转换为 Markdown 或 AsciiDoc 的命令行工具。不需要写代码，就可以进行转换。

下载swagger2markup-cli的地址链接:https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup-cli

执行命令把json文件转换成AsciiDoc文件

在下载的jar包的路径下,通过使用doc窗口,输入命令行:

java -jar swagger2markup-cli-1.3.3.jar convert -i http://127.0.0.1:9007/hgyq/v2/api-docs -f E:\api

命令行中swagger2markup-cli-1.3.3.jar换成自己所下载的jar包版本

-i代表你要转换的文件,后面跟着你的api-docs的地址,也就是API文档json的地址

-f代表转换后输出的AsciiDoc文件地址,不需要带后缀名

执行成功后如图所示:

生成的AsciiDoc文件如图所示

通过AsciiDoctor工具把AsciiDoc文件转换成html文件

Asciidoc 是一种文档写作语言，可以展示出比markdown更好的格式效果。确实如此，我本来想先生成markdown再将markdown格式化，但搜索了半天，没有好但方案。于是我就选用了AsciiDoc，AsciiDoc有比较好但工具软件AsciiDoctor。基于这个工具可以简单快捷但生成类JavaDoc html文件，并且显示效果更好。

下载Ruby地址链接:下载 Ruby

安装就直接下一步下一步就好了,安装好后,去配置一下环境变量,这个就不说了

一旦Ruby安装完毕，你可以使用gem（Ruby的包管理器）来安装Asciidoctor。打开命令行工具，输入以下命令

gem install asciidoctor

就可以下载asciidoctor工具了

asciidoctor安装好后,最后执行转换命令

asciidoctor -d book -a toc=left -a sectnums api.adoc

会生成html文件

以上就是生成swagger2离线API文档的方法了