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这种侵入性小的转换方式，它的主要操作步骤如下

1. 下载swagger2markup-cli到本地(本地已安装jre)
   去github https://github.com/Swagger2Ma... , 下载最新代码，编译一个jar包即可。
   默认的swagger2markup-cli生成英文的AsciiDoc文档，如果要生成中文markdown文档，需要将语言设置为中文，将文档格式设置为Markdown。 配置如下，建议将这些配置保存到文档config.properties中。

   swagger2markup.markupLanguage=MARKDOWN
   swagger2markup.outputLanguage=ZH

2. 获取swagger-json文件的路径
   采用swagger 注解的Spring Boot工程启动后，就可以从 URL "base路径"/v2/api-docs接口可以获得 swagger-json文件
3. 执行命令 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文件，并且显示效果更好。

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

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