api-spec-generator

# API Spec Generator 生成符合 OpenAPI 3.0 规范的 api-spec.yaml 文件，用于解耦前后端开发。 ## 核心价值 ``` api-spec.yaml = 前后端开发的"合同" ↓ 前端和后端基于同一份规范独立开发 ↓ 最终对接时不再扯皮 ``` ## 工作流程 ``` ┌────────────────────────────────────────────────────┐ │ 1. 收集需求 │ │ - 项目类型（用户管理/订单/博客/电商/...） │ │ - 需要哪些接口（CRUD） │ │ - 数据模型有哪些字段 │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ 2. 生成规范 │ │ - 自动推断合理的 RESTful 路径 │ │ - 生成完整的 schema 定义 │ │ - 包含请求/响应示例 │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ 3. 校验完整性 │ │ - 路径是否符合规范 │ │ - HTTP 方法是否正确 │ │ - schema 是否完整 │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ 4. 输出文件 │ │ - api-spec.yaml │ │ - 保存到项目根目录 │ └────────────────────────────────────────────────────┘ ``` ## 触发时机 | 用户说... | 是否触发 | |-----------|----------| | 帮我生成 API 规范 | ✅ | | 创建 api-spec | ✅ | | 设计接口 | ✅ | | 前后端分离 | ✅ | | 用户管理有哪些接口 | ✅ | | 这个项目需要哪些 API | ✅ | ## 信息收集（按需） ### 最小信息（必需） ``` 用户只需要告诉我： - 项目/功能名称 - 数据模型（字段列表） - 需要哪些操作（增删改查） 示例： "帮我生成用户管理的 API 规范 - 用户有：id, name, email - 需要：增删改查" ``` ### 完整信息（可选） 如果你能获取到更多细节： | 信息 | 用途 | 来源 | |------|------|------| | 项目类型 | 推断合理的接口设计 | 对话或现有代码 | | 业务规则 | 添加验证规则 | 需求文档 | | 认证方式 | 添加安全配置 | 项目规范 | | 关系数据 | 添加关联 schema | 数据模型 | ## 输出格式 ### 文件位置 ``` 项目根目录/ └── api-spec.yaml # OpenAPI 3.0 规范文件 ``` ### 文件结构 ```yaml openapi: 3.0.0 info: title: [项目名称] description: [项目描述] version: 1.0.0 servers: - url: http://localhost:8000/api/v1 description: 开发环境 paths: /[资源名]: get: summary: 获取列表 tags: [[标签]] parameters: - name: page in: query schema: type: integer responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/[Schema名]' post: summary: 创建 requestBody: content: application/json: schema: $ref: '#/components/schemas/[RequestSchema]' responses: '201': description: 创建成功 /[资源名]/{id}: get: summary: 获取详情 parameters: - name: id in: path required: true responses: '200': description: 成功 '404': $ref: '#/components/responses/NotFound' put: summary: 更新 responses: '200': description: 成功 '404': $ref: '#/components/responses/NotFound' delete: summary: 删除 responses: '204': description: 删除成功 '404': $ref: '#/components/responses/NotFound' components: schemas: [Schema名]: type: object properties: id: type: integer ... required: - id responses: NotFound: description: 资源不存在 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: ErrorResponse: type: object properties: code: type: integer message: type: string ``` ## 命名规范 ### 路径命名（kebab-case） | 场景 | 路径 | 说明 | |------|------|------| | 资源复数 | /users | 列表、创建 | | 资源单数 | /users/{id} | 详情、更新、删除 | | 动作 | /users/{id}/activate | 特殊动作 | ### HTTP 方法 | 方法 | 用途 | 示例 | |------|------|------| | GET | 查询 | GET /users | | POST | 创建 | POST /users | | PUT | 全量更新 | PUT /users/{id} | | PATCH | 部分更新 | PATCH /users/{id} | | DELETE | 删除 | DELETE /users/{id} | ### Schema 命名（PascalCase） | 用途 | 命名 | 示例 | |------|------|------| | 数据模型 | [资源名] | User, Todo, Order | | 创建请求 | Create[资源名]Request | CreateUserRequest | | 更新请求 | Update[资源名]Request | UpdateUserRequest | | 列表响应 | [资源名]ListResponse | UserListResponse | | 错误响应 | ErrorResponse | 全局通用 | ## 常见数据模型模板 ### 用户管理 ```yaml User: type: object properties: id: { type: integer } username: { type: string } email: { type: string, format: email } password: { type: string } created_at: { type: string, format: date-time } updated_at: { type: string, format: date-time } ``` ### 待办事项 ```yaml Todo: type: object properties: id: { type: integer } title: { type: string } description: { type: string, nullable: true } completed: { type: boolean, default: false } priority: { type: integer, enum: [1,2,3] } created_at: { type: string, format: date-time } ``` ### 分页响应 ```yaml ListResponse: type: object properties: total: { type: integer } page: { type: integer } page_size: { type: integer } items: { type: array, items: { $ref: '#/components/schemas/实体名' } } ``` ## 校验清单 生成规范后，检查以下内容： - [ ] 每个接口有 summary（中文） - [ ] 所有参数有 name、type、description - [ ] 必填参数标记 required - [ ] 路径参数标记 in: path + required: true - [ ] 响应包含状态码（200、201、204、400、404） - [ ] 错误响应使用 $ref 复用 - [ ] schema 字段类型正确（string/integer/boolean/array） - [ ] 日期格式使用 date-time - [ ] 邮箱格式使用 format: email ## 交互示例 ### 示例 1：简洁需求 ``` 用户：帮我生成用户管理的 API 规范 AI： 正在生成 api-spec.yaml... ✅ 完成！创建了以下接口： - GET /users - 获取用户列表 - POST /users - 创建用户 - GET /users/{id} - 获取用户详情 - PUT /users/{id} - 更新用户 - DELETE /users/{id} - 删除用户 文件已保存到：api-spec.yaml ``` ### 示例 2：详细需求 ``` 用户：帮我生成博客系统的 API 规范 - 文章有：id, title, content, author, created_at, updated_at - 评论有：id, article_id, content, author, created_at - 需要：文章的增删改查、评论的增删查 AI： 正在生成 api-spec.yaml... ✅ 完成！ 包含 schema： - Article、CreateArticleRequest、UpdateArticleRequest、ArticleListResponse - Comment、CreateCommentRequest、CommentListResponse 包含路径： - /articles（GET、POST） - /articles/{id}（GET、PUT、DELETE） - /articles/{id}/comments（GET、POST） - /comments/{id}（DELETE） 文件已保存到：api-spec.yaml ``` ## 输出文件 最终输出一个 `api-spec.yaml` 文件，包含： 1. **完整的 OpenAPI 3.0 结构** 2. **所有接口定义**（paths） 3. **所有数据模型**（components/schemas） 4. **通用响应定义**（components/responses） 5. **中文注释**（summary、description） ## 后续建议 生成规范后，主动建议用户： ``` 规范已生成！接下来可以： 1. 【并行开发】并行开发前后端 → 告诉我"并行开发"，我会启动多个子代理 2. 【单独开发】先开发后端 → 基于规范实现 FastAPI 路由 3. 【单独开发】先开发前端 → 基于规范生成 TypeScript 类型 + Mock 数据 ``` ## 参考文件 - `references/openapi-template.yaml` - OpenAPI 3.0 完整模板 - `references/examples.md` - 常见场景示例 ## 注意事项 1. **不要过度设计**：只生成用户需要的接口 2. **保持简洁**：不需要 authentication、security 等高级特性（除非用户要求） 3. **中文优先**：summary、description 使用中文 4. **立即可用**：生成的规范可以直接被 FastAPI、Swagger 等工具使用