Menu
API 文档生成工具。适用于任何后端技术栈的 API 接口文档生成和维护，确保前后端接口规范统一。
| name | api-documentation |
| description | API 文档生成工具。适用于任何后端技术栈的 API 接口文档生成和维护，确保前后端接口规范统一。 |
本技能用于生成和维护 API 接口文档，提供标准化的文档格式和规范。适用于任何后端技术栈（Java、Python、Node.js、Go 等）和任何前端框架（React、Vue、Angular 等）。
|| 后端技术栈 | 支持框架 | ||-------------|----------| || Java | Spring Boot, JAX-RS, Vert.x | || Python | Flask, FastAPI, Django | || JavaScript | Express, NestJS, Koa | || Go | Gin, Echo, Fiber | || 其他 | 任何支持 HTTP 的框架 |
|| 前端技术 | 支持框架 | ||----------|----------| || JavaScript | React, Vue, Angular | || 移动端 | iOS, Android, Flutter, React Native |
每个 API 文档应包含以下部分：
# {模块名} API
## 1. 基础信息
- Base URL
- 认证方式
- 通用响应格式
## 2. 接口列表
- 接口1
- 接口2
- ...
## 3. 错误码
- 错误码定义
- 错误处理建议
## 接口名称
**接口描述：** 简短描述接口功能
**功能说明：** 详细描述接口的业务用途
**接口地址：** /api/v1/endpoint
**请求方式：** GET/POST/PUT/DELETE/PATCH
**Content-Type：** application/json
**认证要求：** 需要/不需要 Token
**请求参数**：
| 参数名 | 位置 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|--------|
| id | Path | int | 是 | 资源ID | 123 |
| name | Body | string | 是 | 名称 | "测试" |
**请求示例**：
```json
{
"name": "测试名称",
"value": 100
}
响应示例：
{
"code": 200,
"message": "操作成功",
"data": {
"id": 123,
"name": "测试名称"
},
"timestamp": "2026-01-19T10:30:00Z"
}
响应字段说明：
| 字段名 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码 |
| message | string | 响应消息 |
| data | object | 实际数据 |
| timestamp | string | 响应时间戳 |
错误响应示例：
{
"code": 400,
"message": "参数错误：name 不能为空",
"error": "INVALID_PARAMETER"
}
---
## RESTful API 设计原则
### HTTP 方法使用规范
|| HTTP方法 | 用途 |幂等性 | 是否安全 |
|-----------|------|--------|----------|
| GET | 获取资源（查询）| 是 | 是 |
| POST | 创建资源（新增）| 否 | 否 |
| PUT | 完整更新资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| DELETE | 删除资源 | 是 | 否 |
### URL 设计规范
#### 资源命名
- 使用名词复数形式
- 使用小写字母
- 使用连字符（-）分隔单词
- 使用层级关系表示嵌套资源
**示例**：
✅ 正确： GET /api/v1/users GET /api/v1/users/123 POST /api/v1/users PUT /api/v1/users/123 DELETE /api/v1/users/123
❌ 错误： GET /api/v1/getUsers GET /api/v1/user GET /api/v1/UserList
#### 查询参数
- 使用 Query 参数传递筛选条件
- 使用分页参数处理列表
**示例**：
GET /api/v1/users?page=1&pageSize=20&status=active
参数说明：
### 分页规范
#### 标准分页参数
|| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|----------|--------|
| page | int | 否 | 1 | 页码（从1开始） |
| pageSize | int | 否 | 20 | 每页数量 |
| sortBy | string | 否 | id | 排序字段 |
| sortOrder | string | 否 | asc | 排序方向（asc/desc） |
#### 响应格式
```json
{
"code": 200,
"message": "查询成功",
"data": [
{
"id": 1,
"name": "item1"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
以下命名方式是业界广泛使用的标准命名规范：
||| 功能 | 路由命名 | HTTP方法 | 说明 |
||------|----------|----------|------|
|| 分页查询 | /{module}/queryByPage | POST | 支持分页、模糊搜索、多条件筛选 |
|| 查询全部 | /{module}/queryAll | GET | 查询所有数据 |
|| 按ID查询 | /{module}/queryById | GET | 根据ID查询单条记录 |
|| 新增 | /{module}/insert | POST | 新增数据 |
|| 更新 | /{module}/update | PUT | 更新数据（完整更新） |
|| 删除 | /{module}/delete | DELETE | 根据ID删除数据 |
命名说明：
{module} 替换为你的资源名称（如 users, orders, products）示例：
POST /api/v1/users/queryByPage - 分页查询用户列表
GET /api/v1/users/queryAll - 查询所有用户
GET /api/v1/users/queryById?id=123 - 查询ID为123的用户
POST /api/v1/users/insert - 新增用户
PUT /api/v1/users/update - 更新用户信息
DELETE /api/v1/users/delete?id=123 - 删除ID为123的用户
{
"code": 200,
"message": "操作成功",
"data": {
// 具体数据
}
}
{
"code": 200,
"message": "查询成功",
"data": [
// 数据列表
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
{
"code": 400,
"message": "参数错误：name 不能为空",
"error": "INVALID_PARAMETER",
"details": {
"field": "name",
"constraint": "NOT_NULL"
}
}
|| 状态码 | 说明 | 使用场景 | |---------|------|----------| | 200 | OK | 请求成功 | | 201 | Created | 资源创建成功 | | 204 | No Content | 删除成功（无返回内容） | | 400 | Bad Request | 请求参数错误 | | 401 | Unauthorized | 未认证 | | 403 | Forbidden | 无权限 | | 404 | Not Found | 资源不存在 | | 409 | Conflict | 资源冲突 | | 500 | Internal Server Error | 服务器内部错误 |
业务状态码应在响应体的 code 字段中返回，而不是 HTTP 状态码。
|| code 类型 | 说明 | 示例 | |-----------|------|------| | 200-299 | 成功 | 200（成功）、201（创建成功） | | 400-499 | 客户端错误 | 400（参数错误）、401（未认证） | | 500-599 | 服务器错误 | 500（服务器错误）、503（服务不可用） |
用于标识资源。
示例：
GET /api/v1/users/123
DELETE /api/v1/users/123
PUT /api/v1/users/123
参数：123（用户的 ID）
用于筛选、排序、分页。
示例：
GET /api/v1/users?page=1&pageSize=20&status=active&sortBy=createdAt
参数：
page: 页码pageSize: 每页数量status: 状态筛选sortBy: 排序字段用于创建、更新资源。
示例：
POST /api/v1/users
Content-Type: application/json
{
"name": "张三",
"email": "zhangsan@example.com",
"age": 25
}
用于认证、传递元信息。
示例：
Authorization: Bearer {token}
Content-Type: application/json
X-Request-ID: 123456
请求头：
Authorization: Bearer {token}
示例：
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
https://api.example.com/users
请求头：
X-API-Key: {api_key}
请求头：
Authorization: Basic {base64(username:password)}
|| 错误类型 | HTTP状态码 | 业务码 | 说明 | |-----------|-------------|---------|------| | 参数错误 | 400 | 4001 | 缺少必填参数、参数类型错误 | | 认证错误 | 401 | 4002 | Token 无效或过期 | | 权限错误 | 403 | 4003 | 无权限访问资源 | | 资源不存在 | 404 | 4004 | 请求的资源不存在 | | 资源冲突 | 409 | 4005 | 资源已存在或状态冲突 | | 服务器错误 | 500 | 5001 | 服务器内部错误 |
参数错误：
{
"code": 400,
"message": "参数错误：email 格式不正确",
"error": "INVALID_EMAIL_FORMAT",
"details": {
"field": "email",
"value": "invalid-email",
"constraint": "EMAIL_FORMAT"
}
}
认证错误：
{
"code": 401,
"message": "认证失败：Token 已过期，请重新登录",
"error": "TOKEN_EXPIRED"
}
|| JSON类型 | 说明 | 示例 | |-----------|------|--------| | string | 字符串 | "hello" | | number | 数字（整数或浮点数）| 123, 3.14 | | boolean | 布尔值 | true, false | | array | 数组 | [1, 2, 3] | | object | 对象 | {"key": "value"} | | null | 空值 | null |
推荐使用 ISO 8601 格式：
{
"createdAt": "2026-01-19T10:30:00Z",
"updatedAt": "2026-01-19T10:30:00+08:00"
}
文档中应明确列出所有可能的值：
**status（状态）**：
| 值 | 说明 |
|-----|------|
| active | 激活 |
| inactive | 未激活 |
| deleted | 已删除 |
/api/v1/users
/api/v2/users
Accept: application/vnd.myapi.v1+json
Warning Header，明确废弃时间根据当前控制器代码生成 API 文档，要求：
1. 提取所有接口（路由、方法、参数、响应）
2. 按照标准文档格式组织内容
3. 包含完整的请求和响应示例
4. 标注认证要求
5. 列出可能的错误码
根据当前 API 调用代码生成接口文档，要求：
1. 提取所有 API 调用（URL、方法、参数）
2. 分析请求和响应的数据结构
3. 生成标准的接口文档格式
4. 补充业务说明和错误处理
检查 API 文档的质量：
1. 是否包含所有必需的字段（接口名称、地址、方法、参数、响应）
2. 示例是否完整且可执行
3. 错误码是否完整且有说明
4. 数据类型是否准确
5. 是否符合 RESTful 设计原则
|| 文档类型 | 命名格式 | 示例 |
|-----------|-----------|------|
| 通用规范 | README.md | API 文档首页 |
| 模块文档 | {module}-api.md | user-api.md |
| 错误码 | error-codes.md | 错误码定义 |
| 认证说明 | authentication.md | 认证方式说明 |
Guidelines for applying Disney's 12 principles of animation to web interfaces. Use when implementing motion, reviewing animation quality, or designing micro-interactions. Triggers on tasks involving CSS animations, transitions, motion libraries, or UX feedback.
Plan, validate, and use 1Password CLI setup for secret injection and auth. Use when tasks need 1Password CLI usage, secret references, op run/read/inject, or provisioning secrets via env vars/.env files and scripts.
Apply 37signals/DHH Rails conventions when writing Ruby on Rails code. Use when building Rails applications, reviewing Rails code, or making architectural decisions. Covers various aspects of Rails application architecture, design and dependencies.
Implement 3D elements and effects using Three.js and React Three Fiber
Expert 4PL and supply chain guidance for logistics operations. Use when discussing supply chain strategy, warehouse management, transportation planning, inventory optimization, 3PL partner management, logistics KPIs, or business strategy for logistics companies. Tailored for the eddication.io platform including DriverConnect driver tracking, job dispatch, and CRM operations.
Apply timeless programming wisdom from "97 Things Every Programmer Should Know" when writing, reviewing, or refactoring code. Use for design decisions, code quality checks, professional development guidance, testing strategies, and workflow optimization.
