swagger-ui + swagger2markup-cli + asciidoctor 生成api文档

最新推荐文章于 2024-09-15 08:04:53 发布

weixin_34054931

最新推荐文章于 2024-09-15 08:04:53 发布

阅读量523

点赞数

CC 4.0 BY-SA版权

文章标签： markdown ruby ui

原文链接：https://my.oschina.net/u/4042451/blog/3051941

本文介绍了利用Swagger生成API文档的方法。通过从GitHub克隆swagger2markup-cli源码，使用Gradle生成jar包，执行指令生成adoc文件，再借助在Windows安装的Ruby和asciidoctor将adoc文件转换为html文件，最终完成API文档生成。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

2019独角兽企业重金招聘Python工程师标准>>>

参考：https://segmentfault.com/a/1190000017873594?utm_source=tag-newest

swagger-ui地址为：http://sample.com:8888/zk/swagger-ui.html

通过https://github.com/Swagger2Markup/swagger2markup-cli clone源码，该工程使用Gradle，用IDEA打开后，View->Tool Windows->Gradle打开Gradle的操作窗口，双击Tasks->build->jar：

在工程目录/build/libs下生成相应的jar包：

执行指令（注意swagger-json文件的URL为swagger-ui的<base url>/v2/api-docs）：

java -jar swagger2markup-cli-1.3.3.jar convert -i http://sample.com:8888/zk/v2/api-docs -f zkong

生成文件zkong.adoc，该文件无法被一般的应用程序打开，需要使用asciidoctor转换为html。为了使用asciidoctor，需要在Windows安装ruby，通过https://rubyinstaller.org/downloads/ 下载ruby安装文件，可以选择WITHOUT DEVKIT的版本:

默认安装，完成之后打开"Start Command Prompt with Ruby", 安装asciidoctor：

gem install Asciidoctor

使用asciidoctor转换adoc文件：

asciidoctor -d book -a toc=left -a sectnums C:\Users\zhusi\code\swagger2markup-cli\build\libs\zkong.adoc

在.adoc文件同目录下会生成.html文件，可用浏览器打开。api文档生成完成。

转载于:https://my.oschina.net/u/4042451/blog/3051941