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 文档。