SpringBoot2基于Swagger2生成离线Api文档

Posted 2023-03-01

参考技术A

Github : https://github.com/ChaselX/springboot-swagger2-offline-api-doc

Gitee : https://gitee.com/chasel96/springboot-swagger2-offline-api-doc

个人觉得 旧版的配置简单许多 ，新版的配置按照官方demo的配置来做还是复杂了很多

配置到Springboot项目中以后，在项目打包的时候便会通过单元测试在指定的目录生成被 官方 称为staticdocs的离线文档

该篇博文引用的依赖都要引入，Spring Rest Docs的依赖spring-restdocs-mockmvc，离线文档的依赖springfox-staticdocs，因为要在单元测试的时候生成文档，所以需要再加测试相关的spring-boot-starter-test。

asciidoctor-maven-plugin 插件会把Asciidoc格式文件转成HTML5格式输出。

这个类包含两个方法，TestApi()是用来生成例子，test()用来生成Asciidoc的文档。生成例子用到了spring-restdocs-mockmvc，每一个API都要进行单元测试才能生成相应的文档片段（snippets），生成的结果如图：

生成完整的Asciidoc文档用到了 Swagger2MarkupConverter ，第一步先获取在线版本的文档并保存到文件 swagger.json 中，第二步把 swagger.json 和之前的例子snippets整合并保存为Asciidoc格式的完整文档。生成结果如图：

通过配置类定义一些文档相关的信息

路径：项目名/docs/asciidoc/index.adoc

利用前面配置的maven插件，只需要执行打包就可以生成相应的文档，如图：

该篇博文引用的依赖都要引入，Spring Rest Docs的依赖spring-restdocs-mockmvc，离线文档的依赖springfox-staticdocs，因为要在单元测试的时候生成文档，所以需要再加测试相关的spring-boot-starter-test。

asciidoctor-maven-plugin 插件会把Asciidoc格式文件转成HTML5格式输出。

这个类包含两个方法，TestApi()是用来生成例子，createSpringfoxSwaggerJson()用来生成Asciidoc的文档。生成例子用到了spring-restdocs-mockmvc，每一个API都要进行单元测试才能生成相应的文档片段（snippets），生成的结果如图：

生成完整的Asciidoc文档用到了 Swagger2MarkupConverter ，第一步先获取在线版本的文档并保存到文件 swagger.json 中，第二步把 swagger.json 和之前的例子snippets整合并保存为Asciidoc格式的完整文档。生成结果如图：

通过配置类定义一些文档相关的信息

在resources目录下创建一个名为logback.xml的配置文件，使用LogstashEncoder作为Default Log Encoder

路径：项目名src/docs/asciidoc/index.adoc

利用前面配置的maven插件，只需要执行打包就可以生成相应的文档，如图：