最近在用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 文档。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。