mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat(docs): add swagger-docs command for RESTful API documentation
Add new /memory:swagger-docs command to generate complete Swagger/OpenAPI documentation following RESTful standards with: - Global security configuration (Bearer Token auth) - Complete endpoint documentation with parameters and responses - Unified error code specification (AUTH/PARAM/BIZ/SYS) - Multi-language support (--lang zh|en, default: zh) - Validation test reports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
catlog22
773
.claude/commands/memory/swagger-docs.md
Normal file
773
.claude/commands/memory/swagger-docs.md
Normal file
@@ -0,0 +1,773 @@
|
||||
---
|
||||
name: swagger-docs
|
||||
description: Generate complete Swagger/OpenAPI documentation following RESTful standards with global security, API details, error codes, and validation tests
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]"
|
||||
---
|
||||
|
||||
# Swagger API Documentation Workflow (/memory:swagger-docs)
|
||||
|
||||
## Overview
|
||||
|
||||
Professional Swagger/OpenAPI documentation generator that strictly follows RESTful API design standards to produce enterprise-grade API documentation.
|
||||
|
||||
**Core Features**:
|
||||
- **RESTful Standards**: Strict adherence to REST architecture and HTTP semantics
|
||||
- **Global Security**: Unified Authorization Token validation mechanism
|
||||
- **Complete API Docs**: Descriptions, methods, URLs, parameters for each endpoint
|
||||
- **Organized Structure**: Clear directory hierarchy by business domain
|
||||
- **Detailed Fields**: Type, required, example, description for each field
|
||||
- **Error Code Standards**: Unified error response format and code definitions
|
||||
- **Validation Tests**: Boundary conditions and exception handling tests
|
||||
|
||||
**Output Structure** (--lang zh):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── 概述/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── 认证说明.md # Authentication guide
|
||||
│ ├── 错误码规范.md # Error code definitions
|
||||
│ └── 版本历史.md # Version history
|
||||
├── 用户模块/ # Grouped by business domain
|
||||
│ ├── 用户认证.md
|
||||
│ ├── 用户管理.md
|
||||
│ └── 权限控制.md
|
||||
├── 业务模块/
|
||||
│ └── ...
|
||||
└── 测试报告/
|
||||
├── 接口测试.md # API test results
|
||||
└── 边界测试.md # Boundary condition tests
|
||||
```
|
||||
|
||||
**Output Structure** (--lang en):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── overview/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── authentication.md # Authentication guide
|
||||
│ ├── error-codes.md # Error code definitions
|
||||
│ └── changelog.md # Version history
|
||||
├── users/ # Grouped by business domain
|
||||
│ ├── authentication.md
|
||||
│ ├── management.md
|
||||
│ └── permissions.md
|
||||
├── orders/
|
||||
│ └── ...
|
||||
└── test-reports/
|
||||
├── api-tests.md # API test results
|
||||
└── boundary-tests.md # Boundary condition tests
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:swagger-docs [path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]
|
||||
```
|
||||
|
||||
- **path**: API source code directory (default: current directory)
|
||||
- **--tool**: CLI tool selection (default: gemini)
|
||||
- `gemini`: Comprehensive analysis, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design
|
||||
- `codex`: Implementation validation, code quality
|
||||
- **--format**: OpenAPI spec format (default: yaml)
|
||||
- `yaml`: YAML format (recommended, better readability)
|
||||
- `json`: JSON format
|
||||
- **--version**: OpenAPI version (default: v3.0)
|
||||
- `v3.0`: OpenAPI 3.0.x
|
||||
- `v3.1`: OpenAPI 3.1.0 (supports JSON Schema 2020-12)
|
||||
- **--lang**: Documentation language (default: zh)
|
||||
- `zh`: Chinese documentation with Chinese directory names
|
||||
- `en`: English documentation with English directory names
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
```bash
|
||||
# Get project info
|
||||
bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Create swagger-docs session
|
||||
SlashCommand(command="/workflow:session:start --type swagger-docs --new \"{project_name}-swagger-{timestamp}\"")
|
||||
// Parse output to get sessionId
|
||||
```
|
||||
|
||||
```bash
|
||||
# Update workflow-session.json
|
||||
bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","format":"yaml","openapi_version":"3.0.3","lang":"{lang}","tool":"gemini"}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json)
|
||||
```
|
||||
|
||||
### Phase 2: Scan API Endpoints
|
||||
|
||||
**Discovery Patterns**: Auto-detect framework signatures and API definition styles.
|
||||
|
||||
**Supported Frameworks**:
|
||||
| Framework | Detection Pattern | Example |
|
||||
|-----------|-------------------|---------|
|
||||
| Express.js | `router.get/post/put/delete` | `router.get('/users/:id')` |
|
||||
| Fastify | `fastify.route`, `@Route` | `fastify.get('/api/users')` |
|
||||
| NestJS | `@Controller`, `@Get/@Post` | `@Get('users/:id')` |
|
||||
| Koa | `router.get`, `ctx.body` | `router.get('/users')` |
|
||||
| Hono | `app.get/post`, `c.json` | `app.get('/users/:id')` |
|
||||
| FastAPI | `@app.get`, `@router.post` | `@app.get("/users/{id}")` |
|
||||
| Flask | `@app.route`, `@bp.route` | `@app.route('/users')` |
|
||||
| Spring | `@GetMapping`, `@PostMapping` | `@GetMapping("/users/{id}")` |
|
||||
| Go Gin | `r.GET`, `r.POST` | `r.GET("/users/:id")` |
|
||||
| Go Chi | `r.Get`, `r.Post` | `r.Get("/users/{id}")` |
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Detect API framework type
|
||||
bash(
|
||||
if rg -q "@Controller|@Get|@Post|@Put|@Delete" --type ts 2>/dev/null; then echo "NESTJS";
|
||||
elif rg -q "router\.(get|post|put|delete|patch)" --type ts --type js 2>/dev/null; then echo "EXPRESS";
|
||||
elif rg -q "fastify\.(get|post|route)" --type ts --type js 2>/dev/null; then echo "FASTIFY";
|
||||
elif rg -q "@app\.(get|post|put|delete)" --type py 2>/dev/null; then echo "FASTAPI";
|
||||
elif rg -q "@GetMapping|@PostMapping|@RequestMapping" --type java 2>/dev/null; then echo "SPRING";
|
||||
elif rg -q 'r\.(GET|POST|PUT|DELETE)' --type go 2>/dev/null; then echo "GO_GIN";
|
||||
else echo "UNKNOWN"; fi
|
||||
)
|
||||
|
||||
# 2. Scan all API endpoint definitions
|
||||
bash(rg -n "(router|app|fastify)\.(get|post|put|delete|patch)|@(Get|Post|Put|Delete|Patch|Controller|RequestMapping)" --type ts --type js --type py --type java --type go -g '!*.test.*' -g '!*.spec.*' -g '!node_modules/**' 2>/dev/null | head -200)
|
||||
|
||||
# 3. Extract route paths
|
||||
bash(rg -o "['\"](/api)?/[a-zA-Z0-9/:_-]+['\"]" --type ts --type js --type py -g '!*.test.*' 2>/dev/null | sort -u | head -100)
|
||||
|
||||
# 4. Detect existing OpenAPI/Swagger files
|
||||
bash(find . -type f \( -name "swagger.yaml" -o -name "swagger.json" -o -name "openapi.yaml" -o -name "openapi.json" \) ! -path "*/node_modules/*" 2>/dev/null)
|
||||
|
||||
# 5. Extract DTO/Schema definitions
|
||||
bash(rg -n "export (interface|type|class).*Dto|@ApiProperty|class.*Schema" --type ts -g '!*.test.*' 2>/dev/null | head -100)
|
||||
```
|
||||
|
||||
**Data Processing**: Parse outputs, use **Write tool** to create `${session_dir}/.process/swagger-planning-data.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"generated_at": "2025-01-01T12:00:00+08:00",
|
||||
"project_name": "project_name",
|
||||
"project_root": "/path/to/project",
|
||||
"openapi_version": "3.0.3",
|
||||
"format": "yaml",
|
||||
"lang": "zh"
|
||||
},
|
||||
"framework": {
|
||||
"type": "NESTJS",
|
||||
"detected_patterns": ["@Controller", "@Get", "@Post"],
|
||||
"base_path": "/api/v1"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"file": "src/modules/users/users.controller.ts",
|
||||
"line": 25,
|
||||
"method": "GET",
|
||||
"path": "/api/v1/users/:id",
|
||||
"handler": "getUser",
|
||||
"controller": "UsersController"
|
||||
}
|
||||
],
|
||||
"existing_specs": {
|
||||
"found": false,
|
||||
"files": []
|
||||
},
|
||||
"dto_schemas": [
|
||||
{
|
||||
"name": "CreateUserDto",
|
||||
"file": "src/modules/users/dto/create-user.dto.ts",
|
||||
"properties": ["email", "password", "name"]
|
||||
}
|
||||
],
|
||||
"statistics": {
|
||||
"total_endpoints": 45,
|
||||
"by_method": {"GET": 20, "POST": 15, "PUT": 5, "DELETE": 5},
|
||||
"by_module": {"users": 12, "auth": 8, "orders": 15, "products": 10}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Analyze API Structure
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Analyze controller/route file structure
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.endpoints[].file' | sort -u | head -20)
|
||||
|
||||
# 2. Extract request/response types
|
||||
bash(for f in $(jq -r '.dto_schemas[].file' ${session_dir}/.process/swagger-planning-data.json | head -20); do echo "=== $f ===" && cat "$f" 2>/dev/null; done)
|
||||
|
||||
# 3. Analyze authentication middleware
|
||||
bash(rg -n "auth|guard|middleware|jwt|bearer|token" -i --type ts --type js -g '!*.test.*' -g '!node_modules/**' 2>/dev/null | head -50)
|
||||
|
||||
# 4. Detect error handling patterns
|
||||
bash(rg -n "HttpException|BadRequest|Unauthorized|Forbidden|NotFound|throw new" --type ts --type js -g '!*.test.*' 2>/dev/null | head -50)
|
||||
```
|
||||
|
||||
**Deep Analysis via Gemini CLI**:
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze API structure and generate OpenAPI specification outline for comprehensive documentation
|
||||
TASK:
|
||||
• Parse all API endpoints and identify business module boundaries
|
||||
• Extract request parameters, request bodies, and response formats
|
||||
• Identify authentication mechanisms and security requirements
|
||||
• Discover error handling patterns and error codes
|
||||
• Map endpoints to logical module groups
|
||||
MODE: analysis
|
||||
CONTEXT: @src/**/*.controller.ts @src/**/*.routes.ts @src/**/*.dto.ts @src/**/middleware/**/*
|
||||
EXPECTED: JSON format API structure analysis report with modules, endpoints, security schemes, and error codes
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Strict RESTful standards | Identify all public endpoints | Document output language: {lang}
|
||||
" --tool gemini --mode analysis --cd {project_root}
|
||||
```
|
||||
|
||||
**Update swagger-planning-data.json** with analysis results:
|
||||
|
||||
```json
|
||||
{
|
||||
"api_structure": {
|
||||
"modules": [
|
||||
{
|
||||
"name": "Users",
|
||||
"name_zh": "用户模块",
|
||||
"base_path": "/api/v1/users",
|
||||
"endpoints": [
|
||||
{
|
||||
"path": "/api/v1/users",
|
||||
"method": "GET",
|
||||
"operation_id": "listUsers",
|
||||
"summary": "List all users",
|
||||
"summary_zh": "获取用户列表",
|
||||
"description": "Paginated list of system users with filtering by status and role",
|
||||
"description_zh": "分页获取系统用户列表，支持按状态、角色筛选",
|
||||
"tags": ["User Management"],
|
||||
"tags_zh": ["用户管理"],
|
||||
"security": ["bearerAuth"],
|
||||
"parameters": {
|
||||
"query": ["page", "limit", "status", "role"]
|
||||
},
|
||||
"responses": {
|
||||
"200": "UserListResponse",
|
||||
"401": "UnauthorizedError",
|
||||
"403": "ForbiddenError"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"security_schemes": {
|
||||
"bearerAuth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT",
|
||||
"description": "JWT Token authentication. Add Authorization: Bearer <token> to request header"
|
||||
}
|
||||
},
|
||||
"error_codes": [
|
||||
{"code": "AUTH_001", "status": 401, "message": "Invalid or expired token", "message_zh": "Token 无效或已过期"},
|
||||
{"code": "AUTH_002", "status": 401, "message": "Authentication required", "message_zh": "未提供认证信息"},
|
||||
{"code": "AUTH_003", "status": 403, "message": "Insufficient permissions", "message_zh": "权限不足"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Task Decomposition
|
||||
|
||||
**Task Hierarchy**:
|
||||
|
||||
```
|
||||
Level 1: Infrastructure Tasks (Parallel)
|
||||
├─ IMPL-001: Generate main OpenAPI spec file (swagger.yaml)
|
||||
├─ IMPL-002: Generate global security config and auth documentation
|
||||
└─ IMPL-003: Generate unified error code specification
|
||||
|
||||
Level 2: Module Documentation Tasks (Parallel, by business module)
|
||||
├─ IMPL-004: Users module API documentation
|
||||
├─ IMPL-005: Auth module API documentation
|
||||
├─ IMPL-006: Business module N API documentation
|
||||
└─ ...
|
||||
|
||||
Level 3: Aggregation Tasks (Depends on Level 1-2)
|
||||
├─ IMPL-N+1: Generate API overview and navigation
|
||||
└─ IMPL-N+2: Generate version history and changelog
|
||||
|
||||
Level 4: Validation Tasks (Depends on Level 1-3)
|
||||
├─ IMPL-N+3: API endpoint validation tests
|
||||
└─ IMPL-N+4: Boundary condition tests
|
||||
```
|
||||
|
||||
**Grouping Strategy**:
|
||||
1. Group by business module (users, orders, products, etc.)
|
||||
2. Maximum 10 endpoints per task
|
||||
3. Large modules (>10 endpoints) split by submodules
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Count endpoints by module
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.statistics.by_module')
|
||||
|
||||
# 2. Calculate task groupings
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.api_structure.modules[] | "\(.name):\(.endpoints | length)"')
|
||||
```
|
||||
|
||||
**Data Processing**: Use **Edit tool** to update `swagger-planning-data.json` with task groups:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_groups": {
|
||||
"level1_count": 3,
|
||||
"level2_count": 5,
|
||||
"total_count": 12,
|
||||
"assignments": [
|
||||
{"task_id": "IMPL-001", "level": 1, "type": "openapi-spec", "title": "Generate OpenAPI main spec file"},
|
||||
{"task_id": "IMPL-002", "level": 1, "type": "security", "title": "Generate global security config"},
|
||||
{"task_id": "IMPL-003", "level": 1, "type": "error-codes", "title": "Generate error code specification"},
|
||||
{"task_id": "IMPL-004", "level": 2, "type": "module-doc", "module": "users", "endpoint_count": 12},
|
||||
{"task_id": "IMPL-005", "level": 2, "type": "module-doc", "module": "auth", "endpoint_count": 8}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values from workflow-session.json
|
||||
2. Read task groups from swagger-planning-data.json
|
||||
3. Generate Level 1 tasks (infrastructure)
|
||||
4. Generate Level 2 tasks (by module)
|
||||
5. Generate Level 3-4 tasks (aggregation and validation)
|
||||
|
||||
## Task Templates
|
||||
|
||||
### Level 1-1: OpenAPI Main Spec File
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate OpenAPI main specification file",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-openapi-spec",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"priority": "critical"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Generate OpenAPI 3.0.3 compliant swagger.yaml",
|
||||
"Include complete info, servers, tags, paths, components definitions",
|
||||
"Follow RESTful design standards, use {lang} for descriptions"
|
||||
],
|
||||
"precomputed_data": {
|
||||
"planning_data": "${session_dir}/.process/swagger-planning-data.json"
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_analysis_data",
|
||||
"action": "Load API analysis data",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json)"
|
||||
],
|
||||
"output_to": "api_analysis"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate OpenAPI spec file",
|
||||
"description": "Create complete swagger.yaml specification file",
|
||||
"cli_prompt": "PURPOSE: Generate OpenAPI 3.0.3 specification file from analyzed API structure\nTASK:\n• Define openapi version: 3.0.3\n• Define info: title, description, version, contact, license\n• Define servers: development, staging, production environments\n• Define tags: organized by business modules\n• Define paths: all API endpoints with complete specifications\n• Define components: schemas, securitySchemes, parameters, responses\nMODE: write\nCONTEXT: @[api_analysis]\nEXPECTED: Complete swagger.yaml file following OpenAPI 3.0.3 specification\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) $(cat ~/.claude/workflows/cli-templates/prompts/documentation/swagger-api.txt) | Use {lang} for all descriptions | Strict RESTful standards",
|
||||
"output": "swagger.yaml"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/swagger.yaml"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-2: Global Security Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Generate global security configuration and authentication guide",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-security",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document Authorization header format in detail",
|
||||
"Describe token acquisition, refresh, and expiration mechanisms",
|
||||
"List permission requirements for each endpoint"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "analyze_auth",
|
||||
"command": "bash(rg -n 'auth|guard|jwt|bearer' -i --type ts -g '!*.test.*' 2>/dev/null | head -50)",
|
||||
"output_to": "auth_patterns"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate authentication documentation",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive authentication documentation for API security\nTASK:\n• Document authentication mechanism: JWT Bearer Token\n• Explain header format: Authorization: Bearer <token>\n• Describe token lifecycle: acquisition, refresh, expiration handling\n• Define permission levels: public, user, admin, super_admin\n• Document authentication failure responses: 401/403 error handling\nMODE: write\nCONTEXT: @[auth_patterns] @src/**/auth/**/* @src/**/guard/**/*\nEXPECTED: Complete authentication guide in {lang}\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) | Include code examples | Clear step-by-step instructions",
|
||||
"output": "{auth_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{auth_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-3: Unified Error Code Specification
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-003",
|
||||
"title": "Generate unified error code specification",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-error-codes",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Define unified error response format",
|
||||
"Create categorized error code system (auth, business, system)",
|
||||
"Provide detailed description and examples for each error code"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate error code specification document",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive error code specification for consistent API error handling\nTASK:\n• Define error response format: {code, message, details, timestamp}\n• Document authentication errors (AUTH_xxx): 401/403 series\n• Document parameter errors (PARAM_xxx): 400 series\n• Document business errors (BIZ_xxx): business logic errors\n• Document system errors (SYS_xxx): 500 series\n• For each error code: HTTP status, error message, possible causes, resolution suggestions\nMODE: write\nCONTEXT: @src/**/*.exception.ts @src/**/*.filter.ts\nEXPECTED: Complete error code specification in {lang} with tables and examples\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) | Include response examples | Clear categorization",
|
||||
"output": "{error_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{error_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Module API Documentation (Template)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${module_task_id}",
|
||||
"title": "Generate ${module_name} API documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"meta": {
|
||||
"type": "swagger-module-doc",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"module": "${module_name}",
|
||||
"endpoint_count": "${endpoint_count}"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Complete documentation for all endpoints in this module",
|
||||
"Each endpoint: description, method, URL, parameters, responses",
|
||||
"Include success and failure response examples",
|
||||
"Mark API version and last update time"
|
||||
],
|
||||
"focus_paths": ["${module_source_paths}"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_module_endpoints",
|
||||
"action": "Load module endpoint information",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.api_structure.modules[] | select(.name == \"${module_name}\")')"
|
||||
],
|
||||
"output_to": "module_endpoints"
|
||||
},
|
||||
{
|
||||
"step": "read_source_files",
|
||||
"action": "Read module source files",
|
||||
"commands": [
|
||||
"bash(cat ${module_source_files})"
|
||||
],
|
||||
"output_to": "source_code"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate module API documentation",
|
||||
"description": "Generate complete API documentation for ${module_name}",
|
||||
"cli_prompt": "PURPOSE: Generate complete RESTful API documentation for ${module_name} module\nTASK:\n• Create module overview: purpose, use cases, prerequisites\n• Generate endpoint index: grouped by functionality\n• For each endpoint document:\n - Functional description: purpose and business context\n - Request method: GET/POST/PUT/DELETE\n - URL path: complete API path\n - Request headers: Authorization and other required headers\n - Path parameters: {id} and other path variables\n - Query parameters: pagination, filters, etc.\n - Request body: JSON Schema format\n - Response body: success and error responses\n - Field description table: type, required, example, description\n• Add usage examples: cURL, JavaScript, Python\n• Add version info: v1.0.0, last updated date\nMODE: write\nCONTEXT: @[module_endpoints] @[source_code]\nEXPECTED: Complete module API documentation in {lang} with all endpoints fully documented\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) $(cat ~/.claude/workflows/cli-templates/prompts/documentation/swagger-api.txt) | RESTful standards | Include all response codes",
|
||||
"output": "${module_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/${module_dir}/${module_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: API Overview and Navigation
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${overview_task_id}",
|
||||
"title": "Generate API overview and navigation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "...", "IMPL-${last_module_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-overview",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_docs",
|
||||
"command": "bash(find .workflow/docs/${project_name}/api -type f -name '*.md' ! -path '*/{overview_dir}/*' | xargs cat)",
|
||||
"output_to": "all_module_docs"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate API overview",
|
||||
"cli_prompt": "PURPOSE: Generate API overview document with navigation and quick start guide\nTASK:\n• Create introduction: system features, tech stack, version\n• Write quick start guide: authentication, first request example\n• Build module navigation: categorized links to all modules\n• Document environment configuration: development, staging, production\n• List SDKs and tools: client libraries, Postman collection\nMODE: write\nCONTEXT: @[all_module_docs] @.workflow/docs/${project_name}/api/swagger.yaml\nEXPECTED: Complete API overview in {lang} with navigation links\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) | Clear structure | Quick start focus",
|
||||
"output": "README.md"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 4: Validation Tasks
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${test_task_id}",
|
||||
"title": "API endpoint validation tests",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-${overview_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-validation",
|
||||
"agent": "@test-fix-agent",
|
||||
"tool": "codex"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Validate accessibility of all endpoints",
|
||||
"Test various boundary conditions",
|
||||
"Verify exception handling"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_swagger_spec",
|
||||
"command": "bash(cat .workflow/docs/${project_name}/api/swagger.yaml)",
|
||||
"output_to": "swagger_spec"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate test report",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive API test validation report\nTASK:\n• Document test environment configuration\n• Calculate endpoint coverage statistics\n• Report test results: pass/fail counts\n• Document boundary tests: parameter limits, null values, special characters\n• Document exception tests: auth failures, permission denied, resource not found\n• List issues found with recommendations\nMODE: write\nCONTEXT: @[swagger_spec]\nEXPECTED: Complete test report in {lang} with detailed results\nRULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) | Include test cases | Clear pass/fail status",
|
||||
"output": "{test_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{test_dir}/{test_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Language-Specific Directory Mapping
|
||||
|
||||
| Component | --lang zh | --lang en |
|
||||
|-----------|-----------|-----------|
|
||||
| Overview dir | 概述 | overview |
|
||||
| Auth doc | 认证说明.md | authentication.md |
|
||||
| Error doc | 错误码规范.md | error-codes.md |
|
||||
| Changelog | 版本历史.md | changelog.md |
|
||||
| Users module | 用户模块 | users |
|
||||
| Orders module | 订单模块 | orders |
|
||||
| Products module | 商品模块 | products |
|
||||
| Test dir | 测试报告 | test-reports |
|
||||
| API test doc | 接口测试.md | api-tests.md |
|
||||
| Boundary test doc | 边界测试.md | boundary-tests.md |
|
||||
|
||||
## API Documentation Template
|
||||
|
||||
### Single Endpoint Format
|
||||
|
||||
Each endpoint must include:
|
||||
|
||||
```markdown
|
||||
### Get User Details
|
||||
|
||||
**Description**: Retrieve detailed user information by ID, including profile and permissions.
|
||||
|
||||
**Endpoint Info**:
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Method | GET |
|
||||
| URL | `/api/v1/users/{id}` |
|
||||
| Version | v1.0.0 |
|
||||
| Updated | 2025-01-01 |
|
||||
| Auth | Bearer Token |
|
||||
| Permission | user / admin |
|
||||
|
||||
**Request Headers**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| Authorization | string | Yes | `Bearer eyJhbGc...` | JWT Token |
|
||||
| Content-Type | string | No | `application/json` | Request content type |
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| id | string | Yes | `usr_123456` | Unique user identifier |
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
| Field | Type | Required | Default | Example | Description |
|
||||
|-------|------|----------|---------|---------|-------------|
|
||||
| include | string | No | - | `roles,permissions` | Related data to include |
|
||||
|
||||
**Success Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "usr_123456",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"status": "active",
|
||||
"roles": ["user"],
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
},
|
||||
"timestamp": "2025-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Response Fields**:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| code | integer | Business status code, 0 = success |
|
||||
| message | string | Response message |
|
||||
| data.id | string | Unique user identifier |
|
||||
| data.email | string | User email address |
|
||||
| data.name | string | User display name |
|
||||
| data.status | string | User status: active/inactive/suspended |
|
||||
| data.roles | array | User role list |
|
||||
| data.created_at | string | Creation timestamp (ISO 8601) |
|
||||
| data.updated_at | string | Last update timestamp (ISO 8601) |
|
||||
|
||||
**Error Responses**:
|
||||
|
||||
| Status | Code | Message | Possible Cause |
|
||||
|--------|------|---------|----------------|
|
||||
| 401 | AUTH_001 | Invalid or expired token | Token format error or expired |
|
||||
| 403 | AUTH_003 | Insufficient permissions | No access to this user info |
|
||||
| 404 | USER_001 | User not found | User ID doesn't exist or deleted |
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# cURL
|
||||
curl -X GET "https://api.example.com/api/v1/users/usr_123456" \
|
||||
-H "Authorization: Bearer eyJhbGc..." \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
```javascript
|
||||
// JavaScript (fetch)
|
||||
const response = await fetch('https://api.example.com/api/v1/users/usr_123456', {
|
||||
method: 'GET',
|
||||
headers: {
|
||||
'Authorization': 'Bearer eyJhbGc...',
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
const data = await response.json();
|
||||
```
|
||||
```
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/active/
|
||||
└── WFS-swagger-{timestamp}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .process/
|
||||
│ └── swagger-planning-data.json
|
||||
└── .task/
|
||||
├── IMPL-001.json # OpenAPI spec
|
||||
├── IMPL-002.json # Security config
|
||||
├── IMPL-003.json # Error codes
|
||||
├── IMPL-004.json # Module 1 API
|
||||
├── ...
|
||||
├── IMPL-N+1.json # API overview
|
||||
└── IMPL-N+2.json # Validation tests
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
|
||||
```bash
|
||||
# Execute entire workflow
|
||||
/workflow:execute
|
||||
|
||||
# Specify session
|
||||
/workflow:execute --resume-session="WFS-swagger-yyyymmdd-hhmmss"
|
||||
|
||||
# Single task execution
|
||||
/task:execute IMPL-001
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:execute` - Execute documentation tasks
|
||||
- `/workflow:status` - View task progress
|
||||
- `/workflow:session:complete` - Mark session complete
|
||||
- `/memory:docs` - General documentation workflow
|
||||
@@ -0,0 +1,266 @@
|
||||
生成符合 RESTful 规范的完整 Swagger/OpenAPI API 文档。
|
||||
|
||||
## 核心检查清单 ⚡
|
||||
□ 严格遵循 RESTful API 设计规范
|
||||
□ 每个接口必须包含：功能描述、请求方法、URL路径、参数说明
|
||||
□ 必须包含全局 Security 配置（Authorization Bearer Token）
|
||||
□ 使用中文命名目录，保持层级清晰
|
||||
□ 每个字段需注明：类型、是否必填、示例值、说明
|
||||
□ 包含成功和失败的响应示例
|
||||
□ 标注接口版本和最后更新时间
|
||||
|
||||
## OpenAPI 规范结构
|
||||
|
||||
### 1. 文档信息 (info)
|
||||
```yaml
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: {项目名称} API
|
||||
description: |
|
||||
{项目描述}
|
||||
|
||||
## 认证方式
|
||||
所有需要认证的接口必须在请求头中携带 Bearer Token：
|
||||
```
|
||||
Authorization: Bearer <your-token>
|
||||
```
|
||||
version: "1.0.0"
|
||||
contact:
|
||||
name: API 支持
|
||||
email: api-support@example.com
|
||||
license:
|
||||
name: MIT
|
||||
```
|
||||
|
||||
### 2. 服务器配置 (servers)
|
||||
```yaml
|
||||
servers:
|
||||
- url: https://api.example.com/v1
|
||||
description: 生产环境
|
||||
- url: https://staging-api.example.com/v1
|
||||
description: 测试环境
|
||||
- url: http://localhost:3000/v1
|
||||
description: 开发环境
|
||||
```
|
||||
|
||||
### 3. 全局安全配置 (security)
|
||||
```yaml
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT Token 认证
|
||||
|
||||
获取方式：调用 POST /auth/login 接口
|
||||
有效期：24小时
|
||||
刷新：调用 POST /auth/refresh 接口
|
||||
|
||||
security:
|
||||
- bearerAuth: []
|
||||
```
|
||||
|
||||
### 4. 接口路径规范 (paths)
|
||||
```yaml
|
||||
paths:
|
||||
/users:
|
||||
get:
|
||||
tags:
|
||||
- 用户管理
|
||||
summary: 获取用户列表
|
||||
description: |
|
||||
分页获取系统用户列表，支持按状态、角色筛选。
|
||||
|
||||
**适用环境**: 开发、测试、生产
|
||||
**前置条件**: 需要管理员权限
|
||||
operationId: listUsers
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
minimum: 1
|
||||
description: 页码（从1开始）
|
||||
example: 1
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 20
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
description: 每页数量
|
||||
example: 20
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取用户列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserListResponse'
|
||||
example:
|
||||
code: 0
|
||||
message: success
|
||||
data:
|
||||
items:
|
||||
- id: "usr_123"
|
||||
email: "user@example.com"
|
||||
name: "张三"
|
||||
total: 100
|
||||
page: 1
|
||||
limit: 20
|
||||
'401':
|
||||
$ref: '#/components/responses/UnauthorizedError'
|
||||
'403':
|
||||
$ref: '#/components/responses/ForbiddenError'
|
||||
```
|
||||
|
||||
### 5. 数据模型规范 (schemas)
|
||||
```yaml
|
||||
components:
|
||||
schemas:
|
||||
# 基础响应结构
|
||||
BaseResponse:
|
||||
type: object
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- timestamp
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
description: 业务状态码，0表示成功
|
||||
example: 0
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: success
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 响应时间戳
|
||||
example: "2025-01-01T12:00:00Z"
|
||||
|
||||
# 错误响应
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: 错误码
|
||||
example: "AUTH_001"
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息
|
||||
example: "Token 无效或已过期"
|
||||
details:
|
||||
type: object
|
||||
description: 错误详情
|
||||
additionalProperties: true
|
||||
```
|
||||
|
||||
### 6. 统一响应定义 (responses)
|
||||
```yaml
|
||||
components:
|
||||
responses:
|
||||
UnauthorizedError:
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AUTH_001"
|
||||
message: "Token 无效或已过期"
|
||||
ForbiddenError:
|
||||
description: 权限不足
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AUTH_003"
|
||||
message: "权限不足，需要管理员角色"
|
||||
NotFoundError:
|
||||
description: 资源不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "BIZ_002"
|
||||
message: "资源不存在"
|
||||
ValidationError:
|
||||
description: 参数验证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "PARAM_001"
|
||||
message: "参数格式错误"
|
||||
details:
|
||||
field: "email"
|
||||
reason: "邮箱格式不正确"
|
||||
```
|
||||
|
||||
## 接口文档必填项
|
||||
|
||||
每个接口必须包含：
|
||||
|
||||
1. **基本信息**
|
||||
- tags: 所属模块（中文）
|
||||
- summary: 一句话描述
|
||||
- description: 详细说明（含适用环境、前置条件）
|
||||
- operationId: 唯一操作标识
|
||||
|
||||
2. **安全配置**
|
||||
- security: 认证要求
|
||||
|
||||
3. **参数定义**
|
||||
- name: 参数名
|
||||
- in: 位置 (path/query/header/cookie)
|
||||
- required: 是否必填
|
||||
- schema: 类型定义（含 default, minimum, maximum）
|
||||
- description: 参数说明
|
||||
- example: 示例值
|
||||
|
||||
4. **响应定义**
|
||||
- 200: 成功响应（含完整示例）
|
||||
- 400: 参数错误
|
||||
- 401: 认证失败
|
||||
- 403: 权限不足
|
||||
- 404: 资源不存在（如适用）
|
||||
- 500: 服务器错误
|
||||
|
||||
5. **版本信息**
|
||||
- x-version: 接口版本
|
||||
- x-updated: 最后更新时间
|
||||
|
||||
## 错误码规范
|
||||
|
||||
| 前缀 | 类别 | HTTP状态码 | 说明 |
|
||||
|------|------|------------|------|
|
||||
| AUTH_ | 认证错误 | 401/403 | 身份验证相关 |
|
||||
| PARAM_ | 参数错误 | 400 | 请求参数验证 |
|
||||
| BIZ_ | 业务错误 | 409/422 | 业务逻辑相关 |
|
||||
| SYS_ | 系统错误 | 500/503 | 服务器异常 |
|
||||
|
||||
## RESTful 设计规范
|
||||
|
||||
1. **URL 命名**: 使用复数名词，小写，连字符分隔
|
||||
2. **HTTP 方法**: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)、PATCH(部分更新)
|
||||
3. **状态码**: 正确使用 2xx/3xx/4xx/5xx
|
||||
4. **分页**: 使用 page/limit 或 offset/limit
|
||||
5. **筛选**: 使用查询参数
|
||||
6. **版本**: URL 路径 (/v1/) 或 请求头
|
||||
Reference in New Issue
Block a user