<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-UI提供的JSON数据生成离线文档的方法，包括源码获取及使用步骤，适用于希望本地化API文档的开发者。
扫一扫
383
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
