Swagger2Markup：代码与插件生成离线文档详解

Swagger2离线文档是通过Swagger2Markup工具将Swagger生成的API文档转换为易于阅读和分享的格式，如AsciiDoc、Markdown和Confluence。本文档提供了两种生成方式：代码方式和插件方式，适用于SpringBoot 2.0.x和Swagger 2.8.0的环境。 1. Swagger2Markup简介： Swagger2Markup是一个开源项目，旨在帮助开发者将Swagger API文档从JSON格式转换成多种文档格式，如 AsciiDoc、Markdown等，以便在没有网络连接的情况下也能提供静态文档。项目地址为<https://github.com/Swagger2Markup/swagger2markup>，它简化了离线文档的维护和分享过程。 2. 代码方式生成文档： - 第一步：添加依赖： 在`pom.xml`文件中，你需要引入以下依赖： ```xml <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency> <dependency> <groupId>nl.jworks.markdown_to_asciidoc</groupId> <artifactId>markdown_to_asciidoc</artifactId> <version>1.0</version> </dependency> ``` 注意，在离线开发环境中，这些依赖需要手动添加到本地仓库。 - 第二步：编写单元测试： 创建一个单元测试用例，编写生成文档的代码逻辑。例如，你可以编写一个方法，传入Swagger API定义，然后调用`swagger2markup`的API来转换为所需的格式（如Markdown、AsciiDoc）。 3. 插件方式生成文档： - 生成 AsciiDoc 或 Markdown： 配置Swagger UI或Spring Boot应用，添加Swagger2Markup插件，然后在配置文件中指定目标格式，即可在运行时自动生成文档。 - 生成 HTML 和 PDF 文档： 使用Asciidoctor插件，可以将生成的文档转换为HTML或PDF格式。对于PDF，可能需要处理PDF编码问题，确保生成的文档无乱码和空白。 4. 解决PDF问题： 如果遇到PDF格式的问题，可能需要调整PDF渲染设置或者使用特定的PDF工具修复。同时生成HTML和PDF文档可以帮助确保不同格式的一致性。 5. 相关文章推荐： - SpringBoot集成Swagger2：介绍了如何在SpringBoot项目中集成Swagger2，并关注常用API的使用。 - 离线文档格式：除了本文的主题，还有关于PDF和HTML5格式的文档生成方法。 - 其他问题解决方案：提到Shiro整合 Swagger2时，可能会遇到样式加载问题，这部分提供了解决方案。 Swagger2离线文档生成是一个实用的功能，通过代码和插件方式实现，能够方便地将Swagger API文档转换成各种可读格式，适合开发过程中和团队分享文档的需求。