OPENAPI_TO_API_GUIDE.md
6.98 KB
OpenAPI 转 API 文档生成器
📖 功能说明
这是一个自动化工具，可以从 docs/api-specs 目录读取 OpenAPI 规范的 Markdown 文档，自动生成标准化的 JavaScript API 接口文件到 src/api/ 目录。
📁 目录结构
输入目录结构
docs/api-specs/
├── 模块名1/
│ ├── 接口名1.md
│ ├── 接口名2.md
│ └── ...
└── 模块名2/
└── 接口名3.md
输出目录结构
src/api/
├── 模块名1.js (自动生成)
├── 模块名2.js (自动生成)
└── ...
📝 OpenAPI 文档格式
每个 .md 文件需要包含 OpenAPI 3.x YAML 规范。参考格式：
# 接口标题
## OpenAPI Specification
\```yaml
openapi: 3.0.1
info:
title: ''
version: 1.0.0
paths:
/srv/:
get: # 或 post
summary: 接口描述
description: 详细描述
tags:
- 模块名
parameters:
- name: a
in: query
example: action_name # 提取为接口的 action
schema:
type: string
- name: f
in: query
example: behalo
schema:
type: string
- name: page
in: query
description: 页码
required: false
example: 1
schema:
type: integer
responses:
'200':
description: 成功响应
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0=失败，1=成功
msg:
type: string
description: 错误信息
data:
type: object
properties:
user:
type: object
properties:
id:
type: integer
description: 用户ID
name:
type: string
description: 姓名
list:
type: array
items:
type: object
properties:
id:
type: integer
description: ID
title:
type: string
description: 标题
\```
🔑 关键字段说明
生成器会从 OpenAPI 文档中提取以下信息：
| 字段 | 说明 | 示例 |
|---|---|---|
summary |
接口描述，用于 JSDoc 注释 | "查询我的信息" |
parameters[].name='a' |
GET 请求的 action 参数 | user_info |
requestBody.properties.a |
POST 请求的 action 参数 | user_edit |
parameters[].in='query' |
GET 请求的查询参数 |
page, pageSize
|
requestBody |
POST 请求的 body 参数 |
name, avatar
|
parameters[].in='header' |
Header 参数（自动过滤） | 不显示在 JSDoc |
get / post
|
HTTP 方法 | 决定使用 fetch.get 或 fetch.post
|
responses['200'].schema |
响应数据结构 | 用于生成 JSDoc @returns |
description |
字段描述 | 用于生成详细注释 |
| 文件名 | API 函数名的基础 |
getUserInfo.md → getUserInfoAPI()
|
📌 JSDoc 注释生成规则
GET 请求参数注释（@param）
- 从
parameters中提取in: query的参数 - 过滤掉
a、f参数和in: header的参数 - 提取参数名、类型、描述
- 标记必填/可选状态
POST 请求参数注释（@param）
- 从
requestBody中提取参数 - 过滤掉
a、f参数 - 过滤掉
in: header的参数 - 提取参数名、类型、描述
- 标记必填/可选状态
返回值注释（@returns）
- 自动解析嵌套对象结构
- 提取每个字段的类型和描述
- 支持数组类型（Array<>）
- 支持多层嵌套对象
🚀 使用方法
1. 运行生成器
pnpm api:generate
2. 查看生成结果
生成的 API 文件会保存到 src/api/ 目录，格式如下：
import { fn, fetch } from '@/api/fn';
const Api = {
GetUserInfo: '/srv/?a=user_info',
}
/**
* @description: 查询我的信息
* @param {Object} params 请求参数
* @returns {Promise<{
* code: number; // 状态码
* msg: string; // 消息
* data: {
* user: {
* id: integer; // 用户ID
* name: string; // 姓名
* mobile: string; // 手机号
* };
* checkin: {
* total_days: integer; // 累计打卡天数
* consecutive_days: integer; // 连续打卡天数
* };
* };
* }>}
*/
export const getUserInfoAPI = (params) => fn(fetch.get(Api.GetUserInfo, params));
注释特点：
- ✅ 详细的返回值类型定义
- ✅ 完整的嵌套对象结构
- ✅ 每个字段的类型和描述
- ✅ 支持数组类型（Array<>）
- ✅ 参数类型和描述（如有）
3. 在项目中使用
import { getUserInfoAPI } from '@/api/user';
// 调用接口
const result = await getUserInfoAPI({ id: 123 });
📋 命名规则
常量命名（帕斯卡命名）
- 输入：
getUserInfo.md - 输出：
GetUserInfo: '/srv/?a=user_info'
函数命名（驼峰命名 + API 后缀）
- 输入：
getUserInfo.md - 输出：
export const getUserInfoAPI = (params) => ...
⚠️ 注意事项
-
文件命名：建议使用驼峰命名，如
getUserInfo.md -
Action 参数：确保每个接口的
parameters中有name: a的参数 - 模块隔离：不同模块的接口会生成到不同的文件中
- 文件覆盖：每次运行会覆盖已生成的文件，请勿手动修改生成的文件
🔧 自定义扩展
如需修改生成逻辑，编辑 scripts/generateApiFromOpenAPI.js：
- 修改命名规则：调整
toCamelCase()和toPascalCase()函数 - 修改输出格式：调整
generateApiFileContent()函数 - 添加额外字段：在
parseOpenAPIDocument()函数中提取更多字段
📚 完整示例
参考 docs/api-specs/user/getUserInfo.md 查看完整的 OpenAPI 文档示例。
运行生成器后，查看 src/api/user.js 查看生成的 API 文件。
🎯 最佳实践
- 保持文档同步：修改接口后及时更新 OpenAPI 文档并重新生成
- 版本控制：将生成的 API 文件提交到 Git
- 代码审查：生成后检查生成的代码是否符合预期
- 模块化管理：相关接口放在同一模块文件夹下
🐛 常见问题
Q: 生成失败怎么办？
A: 检查 YAML 格式是否正确，确保使用 yaml 代码块包裹。
Q: 如何添加新的接口？
A: 在对应的模块目录下创建新的 .md 文件，运行生成命令即可。
Q: 如何修改生成格式？
A: 编辑 scripts/generateApiFromOpenAPI.js 中的相关函数。