swagger2生成离线文档

<think>嗯，用户想了解如何使用Swagger生成离线接口文档。我之前收集了几个相关的引用，可能需要先梳理一下这些信息。首先，引用[1]提到导出Swagger2的离线API文档，用户的项目需要给前端联调，但需要离线版本。引用[2]中用户尝试了swagger2markup但遇到依赖问题，转而使用swagger.json转换的方法。引用[3]和[4]则推荐了SwaggerOfflineDoc工具和TableGo，特别是支持Word和Markdown格式。 用户可能不太熟悉这些工具的具体步骤，所以需要分步骤说明。首先，可能需要介绍几种不同的方法，比如使用Swagger UI生成JSON再转换，或者使用第三方工具。然后，针对每种方法给出具体的操作步骤，比如如何导出swagger.json，如何用SwaggerOfflineDoc生成文档，或者如何使用TableGo生成Word文档。同时，用户可能会关心工具的配置和使用教程，需要详细说明每一步，比如安装依赖、执行命令等。 另外，用户可能遇到常见问题，比如依赖错误或格式问题，需要给出解决方案。例如，引用[2]提到swagger2markup的问题，可能需要建议替代方案。还要注意引用对应的来源，确保信息准确。最后，生成相关问题可以帮助用户进一步探索，比如不同工具的比较或如何处理复杂API结构。需要确保回答结构清晰，步骤详细，同时保持自然的中文表达。</think>### 如何用Swagger生成离线接口文档？ 以下是基于不同工具和方法的详细步骤，帮助您高效生成Swagger离线接口文档： --- #### **方法一：通过Swagger UI导出JSON/YAML并转换** 1. **获取Swagger描述文件** 访问在线Swagger UI页面（如`http://localhost:8080/swagger-ui.html`），找到Swagger的JSON/YAML描述文件地址（通常为`/v2/api-docs`），通过浏览器直接下载`swagger.json`文件[^2][^4]。 2. **使用转换工具生成文档** - **SwaggerOfflineDoc工具**（推荐） 下载[SwaggerOfflineDoc](https://gitcode.com/gh_mirrors/sw/SwaggerOfflineDoc)，运行以下命令生成HTML/Word文档： ```bash java -jar swagger-offline-doc.jar -i swagger.json -o output.html -t html ``` [^3] - **第三方在线转换器** 将`swagger.json`上传至[APIMatic](https://www.apimatic.io/)或[Swagger2Postman](https://www.postman.com/)等平台，导出为PDF/Markdown格式。 --- #### **方法二：使用TableGo生成Word/Markdown文档** 1. **配置TableGo** 下载[TableGo](https://tablego.jline.com.cn/)工具，在配置文件中指定Swagger的JSON文件路径和输出格式（Word或Markdown）。 2. **执行生成命令** ```bash java -jar tablego.jar -config swagger-config.yaml ``` 生成后的文档可直接交付客户，支持自定义模板调整样式。 --- #### **方法三：Swagger2Markup（需Maven/Gradle支持）** 1. **添加Maven插件依赖** 在`pom.xml`中添加： ```xml <plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>1.3.3</version> <configuration> <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput> <outputDir>docs/</outputDir> </configuration> </plugin> ``` 2. **生成AsciiDoc/Markdown** 执行命令： ```bash mvn swagger2markup:convert ``` 生成的文档可通过AsciiDoctor进一步转成PDF。 --- ### **常见问题解决** - **依赖加载失败**：检查Maven仓库镜像配置，或改用无需编译的工具（如SwaggerOfflineDoc）[^2]。 - **JSON格式错误**：使用[Swagger Editor](https://editor.swagger.io/)验证`swagger.json`的合法性。 ---

### 使用 Swagger 导出离线接口文档 #### 方法一：使用 swagger2markup 插件 为了将Swagger接口文档导出为Markdown格式，可以采用`swagger2markup`插件。尽管安装和配置此插件可能会遇到一些挑战，比如插件依赖未能成功加载或是Maven命令执行出现问题[^1]，一旦解决这些问题，该方法能提供一种较为标准的方式来生成静态文档。 对于 Maven 项目，在项目的 `pom.xml` 文件中加入如下配置： ```xml <build> <plugins> <plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>1.3.3</version> <configuration> <swaggerInput>${project.basedir}/src/main/resources/swagger.yaml</swaggerInput> <outputDir>${project.build.directory}/generated-docs</outputDir> </configuration> <executions> <execution> <phase>generate-resources</phase> <goals> <goal>convertSwaggerToAsciiDoc</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ``` 运行 `mvn generate-resources` 命令来触发文档生成过程。 #### 方法二：利用在线工具转换 swagger.json 至其他格式 另一种更为简便的方法是从API获取`swagger.json`文件并借助第三方服务将其转成所需的文档格式。这种方法绕过了复杂的构建环境设置，适合希望快速得到结果的情况。 访问 [editor.swagger.io](https://editor.swagger.io/) 并上传或粘贴`swagger.json`内容至编辑器内，之后可以选择不同的客户端生成选项如HTML5页面或者Postman集合等资源下载链接[^4]。 #### 方法三：直接从Swagger UI界面操作 部分部署好的Swagger UI实例允许用户直接点击界面上的按钮保存当前显示的内容作为JSON/YAML文件，再进一步处理这些文件以适应具体需求。某些情况下也提供了直接导出为PDF的功能[^2]。 #### 特殊情况下的定制化解决方案 当只需要针对特定版本或一组选定的API端点创建文档时，可以在Swagger配置阶段通过编程方式控制哪些路径应当被包含进来。这通常涉及到修改Spring Boot应用程序中的Docket Bean定义逻辑，从而实现更精细粒度上的筛选[^3]。