# swagger2-doc-parser

**Repository Path**: swagger2-doc/swagger2-doc-parser

## Basic Information

- **Project Name**: swagger2-doc-parser
- **Description**: 解析swagger2、swagger3文档的JSON文件，转换为特定语言(ts、js和dart)接口代码。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 0
- **Created**: 2022-03-30
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: api-gateway

**Tags**: None

## README

# Swagger2 Doc Parser

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

[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 📋 目录

- [Swagger2 Doc Parser](#swagger2-doc-parser)
  - [📋 目录](#-目录)
  - [简介](#简介)
    - [核心功能](#核心功能)
  - [快速开始](#快速开始)
    - [安装](#安装)
    - [基本使用](#基本使用)
      - [1. 获取 Swagger 文档](#1-获取-swagger-文档)
      - [2. 编写配置文件](#2-编写配置文件)
      - [3. 生成代码](#3-生成代码)
  - [⚠️ 重要：Swagger tags 命名规范](#️-重要swagger-tags-命名规范)
  - [后端项目支持](#后端项目支持)
    - [Java](#java)
    - [Golang](#golang)
    - [Python](#python)
    - [Node.js](#nodejs)
  - [前端项目支持](#前端项目支持)
  - [项目结构](#项目结构)
  - [测试](#测试)
    - [测试输出示例](#测试输出示例)
  - [AI 支持](#ai-支持)
    - [MCP Server](#mcp-server)
    - [Skills](#skills)
  - [示例项目](#示例项目)
    - [后端项目（提供 Swagger 文档的服务端）](#后端项目提供-swagger-文档的服务端)
    - [前端项目（使用生成 API 的客户端）](#前端项目使用生成-api-的客户端)
  - [文档](#文档)
  - [联系方式](#联系方式)
  - [赞助](#赞助)
  - [License](#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 支持 — 一键生成代码

---

## 快速开始

### 安装

```bash
npm install -g swagger2-doc-parser
```


### 基本使用

#### 1. 获取 Swagger 文档

```bash
# 从远程 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](tests/config-parsets.esm.js)
- JavaScript: [tests/config-parsejs.esm.js](tests/config-parsejs.esm.js)
- Dart: [tests/config-parsedart.esm.js](tests/config-parsedart.esm.js)

#### 3. 生成代码

```bash
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`

```yaml
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        # 测试数据库建表脚本
```

---

## 测试

```bash
# 执行全部测试
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` | 根据配置生成代码 |

配置方式：

```json
{
  "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/` | [📖](examples/backend/java/springboot/java-server/README.md) | `/api/v1/api-docs.json` |
| Java | SpringCloud | `examples/backend/java/springcloud/` | [📖](examples/backend/java/springcloud/README.md) | `/api/v1/api-docs.json` |
| Golang | Gin | `examples/backend/golang/gin/` | [📖](examples/backend/golang/gin/README.md) | `/api/v1/api-docs.json` |
| Golang | Echo | `examples/backend/golang/echo/` | [📖](examples/backend/golang/echo/README.md) | `/api/v1/api-docs.json` |
| Golang | Beego | `examples/backend/golang/beego/` | [📖](examples/backend/golang/beego/README.md) | `/api/v1/api-docs.json` |
| Python | Flask | `examples/backend/python/flask/` | [📖](examples/backend/python/flask/README.md) | `/api/v1/api-docs.json` |
| Python | Django | `examples/backend/python/django/` | [📖](examples/backend/python/django/README.md) | `/api/v1/api-docs.json` |
| Python | FastAPI | `examples/backend/python/fastapi/` | [📖](examples/backend/python/fastapi/README.md) | `/api/v1/api-docs.json` |
| Python | Tornado | `examples/backend/python/tornado/` | [📖](examples/backend/python/tornado/README.md) | `/api/v1/api-docs.json` |
| Node.js | Express | `examples/backend/nodejs/express/` | [📖](examples/backend/nodejs/express/README.md) | `/api/v1/api-docs.json` |
| Node.js | Koa | `examples/backend/nodejs/koa/` | [📖](examples/backend/nodejs/koa/README.md) | `/api/v1/api-docs.json` |

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

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

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

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

---

## 文档

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

- [快速开始](docs/quick-start/zh-CN/index.md)
- [MCP Server 配置](docs/quick-start/zh-CN/mcp-server.md)
- [Skills 使用说明](docs/quick-start/zh-CN/skills.md)
- [后端各框架文档](docs/backend/README.md)
- [前端各平台文档](docs/frontend/README.md)

---

## 联系方式

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

---

## 赞助

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

| 微信支付 | 支付宝 |
|---------|--------|
| ![微信支付](docs/assets/image/README/1648617667411.png) | ![支付宝](docs/assets/image/README/1648617844315.png) |

---

## License

[MIT](LICENSE)