swagger2doc

介绍

swagger文档转换工具，将swagger定义的接口转换为Word、PDF、markdown、eBook、HTML、DOCBOOK 等

软件架构

软件架构说明

如何使用

生成 HTML、PDF、EPUB3、DOCBOOK

说明

支持将swagger.yaml、swagger.json或swagger URL地址,转换为asciidoc,继而转换成其他各种格式,如:HTML、PDF、EPUB3、DOCBOOK等主要用到了两个maven插件:

   1. swagger2markup-maven-plugin   2. asciidoctor-maven-plugin

操作步骤

1. 配置swagger

修改pom.xml中定义的<swagger.input>属性。如下：

<!--<swagger.input>${asciidoctor.resources}/swagger/swagger.json</swagger.input>--><!--<swagger.input>${asciidoctor.resources}/swagger/swagger.yaml</swagger.input>--><swagger.input>http://127.0.0.1:8089/v2/api-docs</swagger.input>

2. 生成文档

执行maven命令

mvn test  

注意事项

1. 若你设计的API中没有用TAG分类,则必须将pom中的<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy> 改为AS-IS或者直接注释掉
2. pdf主题配置过于耗时,这里只是简单设置了下,如果对样式不满意,可以自行参考官方文档配置pdf的样式
3. 若要修改pdf文件字体可将fonts下的字体文件换成你的字体,并在custom-theme.yml中修改font -> catalog的配置,具体请参考pdf文件样式设置指引
4. 因为用到的两个插件不会自动执行,所以指定了插件执行所在的阶段为test,故maven插件目标包含test环节的命令都可以执行。执行完毕后,将在target/asciidoc下会看到生成的文档。

生成word

生产Word需要启动项目，通过调用接口的方式生成文档。

操作步骤

1. 执行执行DocApplication.java，启动工程
2. 访问地址： http://127.0.0.1:8089/swagger-ui.html
3. 选择文档生成方式，swagger2Word支持如下三种方式方式生成 word 文档：

• swagger json 的资源地址： 例如：http://127.0.0.1:8089/v2/api-docs
• 可以通过上传 json 文件
• 可以直接输入 json 字符串

接口如下：

3. 生成的 WORD 示例：

注意事项

样式修改详见resource/templates/word.html

参考链接:

• swagger2markupmaven插件官方文档
• asciidoctor maven插件官方文档
• pom中配置的asciidoctor属性说明
• asciidoctor maven插件中文说明
• asciidoctor maven插件使用范例
• pdf文件样式设置指引
• pdf文件自定义字体设置参考
• swagger-gendoc
• restdocs
• swagger2word

其他

如果觉得不错,请加个星,不甚感激!!!