Menu
用于编写 API 接口文档。当用户需要编写、创建、格式化 API 接口文档时触发，包括描述 API 端点、Header 参数、Body 请求体、响应结果、使用示例等场景。适用于后端 API 文档编写、接口规范制定、API 文档模板生成等任务。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | api-doc |
| description | 用于编写 API 接口文档。当用户需要编写、创建、格式化 API 接口文档时触发，包括描述 API 端点、Header 参数、Body 请求体、响应结果、使用示例等场景。适用于后端 API 文档编写、接口规范制定、API 文档模板生成等任务。 |
你是一位专业的 API 文档工程师，负责编写清晰、规范、易读的 API 接口文档。
每个 API 接口文档必须包含以下章节：
| Method | 用途 | 说明 | 示例 |
|---|---|---|---|
| GET | 查询 | 获取资源列表或单个资源 | 查询用户列表、获取用户详情 |
| POST | 创建 | 创建新资源 | 创建用户、创建订单 |
| PUT | 全量更新 | 替换整个资源 | 更新用户全部信息 |
| PATCH | 部分更新 | 更新资源的部分字段 | 修改用户手机号 |
| DELETE | 删除 | 删除指定资源 | 删除用户、删除订单 |
| Method | Body | 说明 |
|---|---|---|
| GET | 无 | GET 请求不带请求体 |
| POST | 有 | 请求体格式为 JSON |
| PUT | 有 | 请求体格式为 JSON |
| PATCH | 有 | 请求体格式为 JSON |
| DELETE | 无 | DELETE 请求通常不带请求体 |
必须突出显示 Method：
## 获取用户详情
### 🔵 GET /api/v1/users/{userId}
**功能描述**：根据用户 ID 获取用户的详细信息，包括基本信息、扩展资料等。
| 字段 | 值 | 描述 |
|------|-----|------|
| **Method** | **GET** | HTTP 请求方法，必须大写突出显示 |
| **Path** | /api/v1/users/{userId} | 接口路径，{userId} 为路径参数 |
| **描述** | 获取用户详情 | 接口功能简述 |
### Header 参数
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| Authorization | string | 是 | Bearer Token 认证令牌 | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
| Content-Type | string | POST/PUT/PATCH 时必填 | 请求内容类型 | application/json |
| Accept | string | 否 | 接受的内容类型 | application/json |
| Request-ID | string | 否 | 请求唯一标识，用于追踪 | 550e8400-e29b-41d4-a716-446655440000 |
| 认证类型 | Header 值 | 描述 |
|---|---|---|
| Bearer Token | Authorization: Bearer <token> | JWT Token 认证 |
| API Key | Authorization: ApiKey <key> | API 密钥认证 |
| Basic Auth | Authorization: Basic <base64> | 用户名:密码 Base64 编码 |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| userId | integer | 是 | 用户 ID | 12345 |
| orderId | string | 是 | 订单编号 | ORD-20240101-001 |
### Query 参数
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| page | integer | 否 | 页码，默认 1 | 1 |
| pageSize | integer | 否 | 每页数量，默认 20，最大 100 | 20 |
| sort | string | 否 | 排序字段，格式：field:asc/desc | createdAt:desc |
| status | string | 否 | 筛选状态 | active |
| keyword | string | 否 | 搜索关键字 | 张三 |
### Body 请求体
**Content-Type**: application/json
| 字段 | 类型 | 必填 | 描述 | 示例值 |
|------|------|------|------|--------|
| username | string | 是 | 用户名，4-20 位字母或数字 | john_doe |
| email | string | 是 | 邮箱地址，有效邮箱格式 | user@example.com |
| password | string | 是 | 密码，8-32 位 | Password123! |
| phone | string | 否 | 手机号，11 位数字 | 13800138000 |
| gender | string | 否 | 性别：male/female/other | male |
| birthDate | string | 否 | 出生日期，格式：yyyy-MM-dd | 1990-01-15 |
| tags | array | 否 | 用户标签列表 | ["vip","active"] |
| profile | object | 否 | 用户资料对象 | {...} |
{
"username": "john_doe",
"email": "user@example.com",
"password": "Password123!",
"phone": "13800138000",
"gender": "male",
"birthDate": "1990-01-15",
"tags": ["vip", "active"],
"profile": {
"nickname": "John",
"avatar": "https://example.com/avatar.jpg",
"bio": "Hello world"
}
}
| 类型 | 描述 | 示例值 |
|---|---|---|
| string | 字符串 | "hello" |
| integer | 32 位整数 | 123 |
| long | 64 位整数 | 9223372036854775807 |
| float | 单精度浮点数 | 3.14 |
| double | 双精度浮点数 | 3.14159265358979 |
| boolean | 布尔值 | true/false |
| array | 数组 | [1, 2, 3] |
| object | 对象 | {"key": "value"} |
| date | 日期，yyyy-MM-dd 格式 | 2024-01-15 |
| datetime | 日期时间，ISO 8601 格式 | 2024-01-15T10:30:00Z |
### 响应结果
#### 成功响应 (2xx)
| 状态码 | 描述 | 说明 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 204 | No Content | 请求成功但无返回内容（通常用于 DELETE） |
成功响应示例：
{
"code": 200,
"message": "success",
"data": {},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
| 状态码 | 描述 | 说明 |
|---|---|---|
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权或 Token 失效 |
| 403 | Forbidden | 无权限访问 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 请求格式正确但语义错误 |
| 429 | Too Many Requests | 请求过于频繁 |
| 500 | Internal Server Error | 服务器内部错误 |
错误响应示例：
{
"code": 400,
"message": "请求参数验证失败",
"errors": [
{
"field": "email",
"message": "邮箱格式不正确"
}
],
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
| 字段 | 类型 | 描述 |
|---|---|---|
| code | integer | 业务状态码，与 HTTP 状态码对应 |
| message | string | 状态描述信息 |
| data | object/null | 响应数据主体，可为 null |
| errors | array | 错误详情列表，仅错误响应时返回 |
| timestamp | string | 服务器时间戳，ISO 8601 格式 |
| requestId | string | 请求唯一标识，用于日志追踪 |
{
"code": 200,
"message": "success",
"data": {
"list": [],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
接口：GET /api/v1/users/{userId}
请求示例：
curl -X GET "https://api.example.com/api/v1/users/12345" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Accept: application/json"
响应示例：
{
"code": 200,
"message": "success",
"data": {
"userId": 12345,
"username": "john_doe",
"email": "user@example.com",
"phone": "13800138000",
"gender": "male",
"createdAt": "2024-01-15T10:30:00Z"
},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
接口：GET /api/v1/users
请求示例：
curl -X GET "https://api.example.com/api/v1/users?page=1&pageSize=20&status=active" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Accept: application/json"
响应示例：
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"userId": 12345,
"username": "john_doe",
"email": "user@example.com"
},
{
"userId": 12346,
"username": "jane_doe",
"email": "jane@example.com"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
接口：DELETE /api/v1/users/{userId}
请求示例：
curl -X DELETE "https://api.example.com/api/v1/users/12345" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Accept: application/json"
响应示例：
{
"code": 204,
"message": "用户删除成功",
"data": null,
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
接口：POST /api/v1/users
请求示例：
curl -X POST "https://api.example.com/api/v1/users" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Request-ID: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"username": "john_doe",
"email": "user@example.com",
"password": "Password123!",
"phone": "13800138000",
"gender": "male"
}'
响应示例：
{
"code": 201,
"message": "用户创建成功",
"data": {
"userId": 12345,
"username": "john_doe",
"email": "user@example.com",
"phone": "13800138000",
"gender": "male",
"createdAt": "2024-01-15T10:30:00Z"
},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
错误响应示例：
{
"code": 400,
"message": "请求参数验证失败",
"errors": [
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "password",
"message": "密码长度不能少于 8 位"
}
],
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
接口：PUT /api/v1/users/{userId}
请求示例：
curl -X PUT "https://api.example.com/api/v1/users/12345" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"username": "john_doe_updated",
"email": "newemail@example.com",
"password": "NewPassword123!",
"phone": "13900139000",
"gender": "female"
}'
响应示例：
{
"code": 200,
"message": "用户更新成功",
"data": {
"userId": 12345,
"username": "john_doe_updated",
"email": "newemail@example.com",
"phone": "13900139000",
"gender": "female",
"updatedAt": "2024-01-15T11:00:00Z"
},
"timestamp": "2024-01-15T11:00:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440001"
}
接口：PATCH /api/v1/users/{userId}
请求示例：
curl -X PATCH "https://api.example.com/api/v1/users/12345" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"phone": "13900139000"
}'
响应示例：
{
"code": 200,
"message": "用户更新成功",
"data": {
"userId": 12345,
"username": "john_doe",
"email": "user@example.com",
"phone": "13900139000",
"gender": "male",
"updatedAt": "2024-01-15T11:00:00Z"
},
"timestamp": "2024-01-15T11:00:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440002"
}
## [接口名称]
### 🔵 [METHOD] /api/v1/[resource]
**功能描述**：接口的详细功能描述。
| 字段 | 值 | 描述 |
|------|-----|------|
| **Method** | **GET/POST/PUT/PATCH/DELETE** | HTTP 方法 |
| **Path** | /api/v1/resource | 接口路径 |
| **描述** | 功能描述 | 接口简述 |
| **Content-Type** | application/json | POST/PUT/PATCH 时必填 |
### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Authorization | string | 是 | Bearer Token 认证令牌 |
| Content-Type | string | POST/PUT/PATCH | 请求内容类型 |
### Path 参数（如有）
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 资源ID |
### Query 参数（如有）
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| page | integer | 否 | 页码 |
### Body 请求体（如有）
| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| field | string | 是 | 字段描述 |
### 响应结果
#### 成功响应 (2xx)
| 状态码 | 描述 |
|--------|------|
| 200 | OK |
```json
{
"code": 200,
"message": "success",
"data": {},
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "uuid"
}
| 状态码 | 描述 |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
{
"code": 400,
"message": "error message",
"errors": [],
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "uuid"
}
```bash
curl -X [METHOD] "https://api.example.com/api/v1/resource"
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-d '{"field": "value"}'
```
```json { "code": 200, "message": "success", "data": {} } ```
---
## 11. 编写规范检查清单
- [ ] **Method 突出显示**（使用 🔵🟢🟡 等颜色标记或加粗）
- [ ] GET 请求：无 Body，有 Query 参数示例
- [ ] POST 请求：有 Body 请求示例
- [ ] PUT 请求：有 Body 请求示例
- [ ] PATCH 请求：有 Body 请求示例
- [ ] DELETE 请求：有请求示例
- [ ] 包含成功响应示例
- [ ] 包含错误响应示例
- [ ] cURL 示例完整（包含 Header、Body）
- [ ] 响应示例使用格式化 JSON
Use when performing code review, code review after changes, code formatting, editing code, modifying code, or when user asks to review code. Applies to all programming languages (Java, Python, Go, TypeScript, Vue, etc.). Checks: code specifications, class/method comments, comment ratio (≥60%), naming conventions, security rules, exception handling, logging standards, database specs, API design, git commit format, dependency management, code complexity limits, null safety, function parameters limit, code duplication detection, magic numbers/constants, collection capacity, string concatenation, equals/hashCode. Trigger automatically when user modifies or formats code.
Use when user wants to create a story line for business execution. This skill is DRIVEN by the Superpowers brainstorm skill. It scans the codebase, checks for required dependencies (brainstorm skill, chrome-devtools MCP), and guides users through creating a story with 6 core elements: story goals, key nodes/milestones, roles/participants, flow/paths, data flow, and exceptions/boundary cases. Each element is refined via brainstorm after user confirmation. After the story line is generated, Chrome DevTools MCP is MANDATORY for testing - issues must be fixed and retested until all nodes pass. Outputs a Markdown story file, optional code skeleton, and a final test report.
手动或自动保存会话核心内容到 context 文件。 触发方式：用户输入 /save-context，或首次工具调用时自动触发。 保存位置：.ai/context.md（主文件/索引）+ .ai/context-YYYY-MM-DD.md（日期归档/详细内容） 核心功能：记录历史错误与经验教训，避免模型切换后重复犯错。
Use when working on DDD (Domain-Driven Design) architecture — bounded contexts, entities, value objects, aggregates, domain events, repositories, domain services, factories, CQRS, event sourcing. Trigger when user mentions DDD, domain modeling, strategic design, tactical design, CQRS, event sourcing, or asks about architectural patterns for complex business domains.
Use when AI generates code and code cleanup/formatting is needed - removes unused imports, sorts imports alphabetically, removes unused methods, and adds missing Javadoc comments
产品经理最佳实践 — 需求分析、产品规划、用户体验设计、数据驱动决策、A/B测试、敏捷实践、MVP思维。当用户讨论产品需求、用户故事、功能设计、用户体验、数据分析、业务指标、产品迭代，或询问产品决策时触发。