共计 1507 个字符，预计需要花费 4 分钟才能阅读完成。
最近在用 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 文档。
