swagger-ui 转换成文档

最近在用swagger写API手册，写一堆注解后，启动Java工程，API文档就自动生成了，打开swagger-ui.html，效果是这样的。上面可以执行RestAPI，但是用来阅读，非常不得劲。

因为，我们想要下面这样的，哪里不会点哪里。

怎么得到这种效果呢？swagger2markup + AsciiDoc可以帮你达成目标。

Swagger2markup

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

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

我更喜欢swagger2markup-cli这种侵入性小的转换方式，它的主要操作步骤如下

下载swagger2markup-cli到本地(本地已安装jre)
去github https://github.com/Swagger2Ma... , 下载最新代码，编译一个jar包即可。
默认的swagger2markup-cli生成英文的AsciiDoc文档，如果要生成中文markdown文档，需要将语言设置为中文，将文档格式设置为Markdown。配置如下，建议将这些配置保存到文档config.properties中。
```
swagger2markup.markupLanguage=MARKDOWN
swagger2markup.outputLanguage=ZH
```
获取swagger-json文件的路径
采用swagger 注解的Spring Boot工程启动后，就可以从 URL "base路径"/v2/api-docs接口可以获得 swagger-json文件
执行命令 swagger2markup-cli 生成markdown
java -jar swagger2markup-cli-1.3.3.jar convert -i http://127.0.0.1:8090/api/v1/v2/api-docs -c ./config.properties -f lsm
-i 指定swagger json文件可以是url地址
-c 指定配置文件
-f 指定目标文件地址，注意不需要带后缀

执行命令后你就可以得到markdown文件或AsciiDoc文件，但markdown显示后的效果是这样的，并没有我们期待的侧边栏。

AsciiDoctor

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

安装
Asciidoctor 使用ruby写的，我安装是使用gem安装的，gem install Asciidoctor即可。其他环境安装方法请到Asciidoctor官网查询。https://asciidoctor.org/docs/...
转换
执行如下命令，即可得到 lsm.html，显示效果如下图
asciidoctor -d book -a toc=left -a sectnums lsm.adoc
-d 生成文件类型
-a toc=left 指定目录到左侧
-a sectnums 指定生成的文件带section编

至此搞定收工，希望你也能拥有一个满意的API 文档。