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

clipboard.png

clipboard.png

因为,我们想要下面这样的,哪里不会点哪里。
clipboard.png

怎么得到这种效果呢?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显示后的效果是这样的,并没有我们期待的侧边栏。
clipboard.png

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编

    clipboard.png

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


阮粳籼
162 声望29 粉丝

hello world


引用和评论

0 条评论