Swagger2 Doc Parser

解析 Swagger 2/3 (OpenAPI) 文档，自动生成多语言 API 客户端代码。

📋 目录

• Swagger2 Doc Parser
  • 📋 目录
  • 简介
    • 核心功能
  • 快速开始
    • 安装
    • 基本使用
      • 1. 获取 Swagger 文档
      • 2. 编写配置文件
      • 3. 生成代码
  • ⚠️ 重要：Swagger tags 命名规范
  • 后端项目支持
    • Java
    • Golang
    • Python
    • Node.js
  • 前端项目支持
  • 项目结构
  • 测试
    • 测试输出示例
  • AI 支持
    • MCP Server
    • Skills
  • 示例项目
    • 后端项目（提供 Swagger 文档的服务端）
    • 前端项目（使用生成 API 的客户端）
  • 文档
  • 联系方式
  • 赞助
  • License

简介

swagger2-doc-parser 是一个跨语言 API 代码生成工具。它解析 Swagger 2.0 和 OpenAPI 3.0 文档，生成指定语言（TypeScript、JavaScript、Dart等）的 API 客户端代码。

核心功能

• ✅ 支持 Swagger 2.0 和 OpenAPI 3.0 文档解析
• ✅ 支持 11 种后端框架 的服务端提供的 Swagger 文档
• ✅ 根据后端 Swagger 文档，生成 6 种前端平台 的客户端 API 代码
• ✅ 自定义模板引擎 — 完全掌控输出代码风格
• ✅ MCP Server 集成 — AI 编程助手直接调用
• ✅ Skills 支持 — 一键生成代码

快速开始

安装

npm install -g swagger2-doc-parser

基本使用

1. 获取 Swagger 文档

# 从远程 URL 获取
swagger2-doc-parser fetch http://localhost:8080/api/v1/api-docs.json -d ./scripts/api-doc.json

2. 编写配置文件

配置参考:

• Typescript: tests/config-parsets.esm.js
• JavaScript: tests/config-parsejs.esm.js
• Dart: tests/config-parsedart.esm.js

3. 生成代码

swagger2-doc-parser gen -c ./tests/config-parsets.esm.js -o ./src/controllers -d ./scripts/api-doc.json

⚠️ 重要：Swagger tags 命名规范

Swagger/OpenAPI 文档中的 tags 字段禁止使用中文！

tags 的值会被直接用作生成的代码文件名和类名。使用中文会导致：

| ❌ 错误示例 | ✅ 正确示例 | |-----------|-----------| | tags: [用户管理] → 生成 用户管理.ts | tags: [UserController] → 生成 UserController.ts | | tags: [角色管理] → 生成 角色管理.ts | tags: [RoleController] → 生成 RoleController.ts |

推荐命名规则： 使用英文驼峰格式 XxxController

tags:
  - name: UserController   # ✅ 正确
  - name: RoleController   # ✅ 正确
  - name: DeptController   # ✅ 正确
  - name: MenuController   # ✅ 正确
  - name: PostController   # ✅ 正确

后端项目支持

Java

| 框架 | 目录 | 说明 | |------|------|------| | SpringBoot | examples/backend/java/springboot/ | MyBatis-Plus + MySQL + Swagger | | SpringCloud | examples/backend/java/springcloud/ | Gateway + Eureka + MyBatis-Plus |

Golang

| 框架 | 目录 | 说明 | |------|------|------| | Gin | examples/backend/golang/gin/ | Controller/Service/Dao 三层架构 | | Echo | examples/backend/golang/echo/ | Echo v4 + MySQL | | Beego | examples/backend/golang/beego/ | Beego v2 + ORM |

Python

| 框架 | 目录 | 说明 | |------|------|------| | Flask | examples/backend/python/flask/ | Flask + PyMySQL | | Django | examples/backend/python/django/ | DRF ViewSet + Serializer | | FastAPI | examples/backend/python/fastapi/ | SQLAlchemy + Uvicorn | | Tornado | examples/backend/python/tornado/ | Tornado 异步 + PyMySQL |

Node.js

| 框架 | 目录 | 说明 | |------|------|------| | Express | examples/backend/nodejs/express/ | Express + mysql2 + Swagger-jsdoc | | Koa | examples/backend/nodejs/koa/ | Koa + koa-router + mysql2 |

统一数据库 Schema： docs/assets/schema.sql（包含 10 张表：用户、组织、菜单、角色、岗位、菜单关联表 × 3、菜单接口、Casbin 权限）

前端项目支持

| 平台 | 语言 | 目录 | 配置文件 | |------|------|------|---------| | React | TypeScript | examples/frontend/react/react-ts/ | scripts/config.ts.js | | React Native | JavaScript | examples/frontend/react-native/javascript/ | scripts/config.js.js | | Vue | JavaScript | examples/frontend/vue/vue-ts/ | scripts/config.js | | Flutter | Dart | examples/frontend/flutter/flutter/ | scripts/config.dart.js | | 微信小程序 | JavaScript | examples/frontend/miniprogram/wechat/ | scripts/config.js | | uni-app | JavaScript | examples/frontend/uni-app/uni-app/ | scripts/config.js |

项目结构

swagger2-doc-parser/
├── src/                          # 核心 TypeScript 源码
│   ├── index.ts                  # CLI 入口
│   ├── api-gen.ts                # 代码生成器
│   ├── api-get.ts                # 远程文档获取
│   ├── config.ts                 # 默认配置 (Dart 模板)
│   └── helpers/                  # 工具库
│       ├── Api.ts                # API 解析
│       ├── Definition.ts         # 实体定义解析
│       ├── FileHelper.ts         # 文件操作
│       ├── mergeConfig.ts        # 配置合并
│       └── utils.ts              # 命名工具
├── dist/                         # 编译输出
├── docs/                         # 文档
│   ├── quick-start/zh-CN/        # 快速开始
│   ├── backend/                  # 后端框架文档
│   └── frontend/                 # 前端平台文档
├── examples/                     # 示例项目
│   ├── backend/                  # 11 个后端框架示例
│   └── frontend/                 # 6 个前端平台示例
├── test/                         # 测试
│   ├── get-api.ts                # 获取远程 Swagger 文档
│   ├── config-parsets.esm.js     # TS 配置示例
│   ├── config-parsedart.esm.js   # Dart 配置示例
│   ├── config-parsejs.esm.js     # JavaScript 配置示例
│   └── api-doc.json              # 测试用 Swagger 文档
└── docs/assets/schema.sql        # 测试数据库建表脚本

测试

# 执行全部测试
npm test

# 单语言测试
npm run test:ts       # TypeScript 代码生成测试
npm run test:dart     # Dart 代码生成测试
npm run test:js       # JavaScript 代码生成测试
npm run test:fetch    # 远程文档获取测试

# 实时 API 测试（需先启动后端）
# cd examples/backend/nodejs/express
# MYSQL_PASSWORD='<your_mysql_password>' node app.js
# curl http://localhost:8080/api/v1/api-docs.json

测试输出示例

📁 生成的文件 (6 个):
   📁 definitions/ (3 个文件)
      📄 Definition.ts, R.ts, SysUserReq.ts
   📄 UserController.ts (36 行)
   📄 RoleController.ts (26 行)
   📄 DeptController.ts (11 行)
   📄 MenuController.ts (11 行)
   📄 PostController.ts (11 行)
✅ API 接口文件生成成功

AI 支持

MCP Server

项目 swagger2-doc-mcp (feature-ts 分支) 提供了 Model Context Protocol 服务：

| 工具 | 功能 | |------|------| | fetch | 获取远程 Swagger 文档 | | gen | 根据配置生成代码 |

配置方式：

{
  "mcpServers": {
    "swagger2-doc": {
      "command": "npx",
      "args": ["swagger2-doc-mcp"]
    }
  }
}

Skills

项目 swagger2-doc-skills (feature-ts 分支) 提供了 AI 技能包：

| 技能 | 功能 | |------|------| | swagger2-doc-gen | 根据 API 文档生成指定平台代码 | | swagger2-doc-fetch | 获取远程 Swagger 文档 |

示例项目

后端项目（提供 Swagger 文档的服务端）

这些项目演示如何配置 Swagger，为前端提供 API 文档端点：

| 语言 | 框架 | 路径 | README | Swagger 端点 | |------|------|------|--------|-------------| | Java | SpringBoot | examples/backend/java/springboot/ | 📖 | /api/v1/api-docs.json | | Java | SpringCloud | examples/backend/java/springcloud/ | 📖 | /api/v1/api-docs.json | | Golang | Gin | examples/backend/golang/gin/ | 📖 | /api/v1/api-docs.json | | Golang | Echo | examples/backend/golang/echo/ | 📖 | /api/v1/api-docs.json | | Golang | Beego | examples/backend/golang/beego/ | 📖 | /api/v1/api-docs.json | | Python | Flask | examples/backend/python/flask/ | 📖 | /api/v1/api-docs.json | | Python | Django | examples/backend/python/django/ | 📖 | /api/v1/api-docs.json | | Python | FastAPI | examples/backend/python/fastapi/ | 📖 | /api/v1/api-docs.json | | Python | Tornado | examples/backend/python/tornado/ | 📖 | /api/v1/api-docs.json | | Node.js | Express | examples/backend/nodejs/express/ | 📖 | /api/v1/api-docs.json | | Node.js | Koa | examples/backend/nodejs/koa/ | 📖 | /api/v1/api-docs.json |

启动后端项目后，通过以上端点获取 Swagger JSON 文档，然后用 swagger2-doc-parser gen 生成前端代码。

前端项目（使用生成 API 的客户端）

这些项目演示如何使用 swagger2-doc-parser 生成的 API 代码：

| 平台 | 语言 | 路径 | README | 说明 | |------|------|------|--------|------| | React | TypeScript | examples/frontend/react/react-ts/ | 📖 | ⭐ 完整管理后台（用户/角色/组织/菜单/岗位 5个管理页面） | | Flutter | Dart | examples/frontend/flutter/flutter/ | 📖 | 自动生成的 API 控制器 + 用户管理页面 | | 微信小程序 | JavaScript | examples/frontend/miniprogram/wechat/ | 📖 | 自动生成的 API + 用户管理页面 | | uni-app | JavaScript | examples/frontend/uni-app/uni-app/ | 📖 | 自动生成的 API + 用户管理页面 | | React Native | JavaScript | examples/frontend/react-native/javascript/ | 📖 | 自动生成的 API + 用户管理页面 | | Vue | JavaScript | examples/frontend/vue/vue-ts/ | 📖 | 自动生成的 API 模块 |

文档

详细文档请查看 docs/ 目录：

• 快速开始
• MCP Server 配置
• Skills 使用说明
• 后端各框架文档
• 前端各平台文档

联系方式

• 微信群：添加 WX liuhong17happy，备注"Swagger2"，同意后邀请进群
• 项目主页：swagger2-doc-parser
• MCP Server：swagger2-doc-mcp
• Skills：swagger2-doc-skills

赞助

如果你觉得本项目对你有用，提提意见或者微不足道的赞助，都是对项目作者最大的支持。

| 微信支付 | 支付宝 | |---------|--------| | | |

License

MIT