【Tools】如何通过swagger导出离线接口文档

### 使用 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]。