Swagger 文档太难读？我做了个一键转 Markdown 的工具

Swagger 文档太难读我做了个一键转 Markdown 的工具作为后端开发你一定经历过这种场景接口写好了 ✅Swagger 也生成了 ✅然后前端来一句 “能不能给我一份 Markdown 文档”……当场沉默 Swagger 的“致命问题”Swagger或者 OpenAPI确实很好用但它有几个非常现实的问题❌ 1. 不适合“阅读”Swagger UI 更像“调试工具”而不是“阅读文档”信息密集层级深不适合快速浏览❌ 2. 不方便沉淀团队常用的文档方式是MarkdownREADME / Wiki飞书 / NotionGit 仓库 Swagger 内容很难直接迁移过去❌ 3. 没有统一输出格式不同项目的 Swagger结构不统一字段说明缺失响应示例不规范 文档质量参差不齐 我是怎么解决这个问题的我直接做了一个工具gotool.top - Swagger 转 Markdowngotool.top核心目标很简单 把 Swagger 变成“人能看懂”的文档⚙️ 工具核心能力 1. 一键转换 Swagger → Markdown只需要粘贴 Swagger JSON / 输入 URL → 点击转换直接输出标准 Markdown接口分组请求方式参数表格响应示例 2. 自动解析字段注释重点很多工具的通病 只解析结构不解析“意义”而这个工具会解析description解析嵌套对象特别是 data生成字段说明表格例如{data:{userName:用户名,age:18}} 会被转成| 字段 | 类型 | 描述 | |------|------|------| | userName | string | 用户名 | | age | int | 年龄 | 3. 自动识别 Swagger / OpenAPI 版本支持Swagger 2.0OpenAPI 3.0无需手动选择自动解析 4. 自动生成示例数据不只是结构 连示例 JSON 都帮你生成好了这点对于前端联调接口测试非常实用 实际效果展示转换前Swagger{/user/info:{get:{summary:获取用户信息}}}转换后Markdown## 获取用户信息 ### 请求方式 GET /user/info ### 请求参数 自动生成 ### 响应示例 json { code: 0, data: { name: 张三 } } 可以直接复制到 - README.md - 接口文档仓库 - 技术博客 --- ## 我在实际项目中的使用方式 我现在的流程是 text 后端写接口 → Swagger 自动生成 ↓ 丢进 gotool.top 转 Markdown ↓ 提交到 Git / Wiki效果 文档产出效率提升‍ 前后端沟通成本下降 文档格式统一 适合哪些人这个工具特别适合‍ 后端开发最刚需 前端开发不用再翻 Swagger 测试工程师写用例更方便 技术负责人统一规范 和其他工具有什么区别很多类似工具的问题❌ 不支持嵌套字段❌ 没有注释解析❌ Markdown 结构混乱而这个工具重点解决✅ “结构 语义”同时输出✅ 文档可以直接用✅ 不需要二次加工 在线使用https://gotool.top打开就能用无需注册基础功能 最后说一句如果你还在手动整理接口文档 在 Swagger 和 Markdown 之间反复横跳 那真的可以试试这个工具 一次转换长期省时间