CRITICAL: This skill should ONLY be triggered when the user explicitly mentions generating API documentation. Do NOT trigger for generic documentation requests without API context.
Workflow Overview
This skill follows a systematic 4-step workflow:
- Scan Code - Check current project or specified objects for Controller classes and API interfaces
- Extract Information - Scan interfaces to collect request URL, method, parameters, and response information
- Generate Documentation - Create API documentation following the standard template
- Save Output - Save documentation to
./docs directory in the current project
Step-by-Step Process
#### Step 1: Scan Code for Interfaces
CRITICAL: Before generating any documentation, you MUST scan the code to find API interfaces.
- Identify Target:
- Ask user if they want to scan the entire project or specific Controller classes
- If no target specified, scan the entire project for Controller classes
- Common Controller patterns:
- Java: @RestController, @Controller with @RequestMapping
- Spring Boot: Classes in controller or web package
- Files ending with Controller.java or Controller.kt
- Scan for Controllers:
- Search for Controller classes in the project
- Identify all classes annotated with @RestController or @Controller
- List all found Controller classes
- Check for Interfaces:
- For each Controller class, scan for methods annotated with:
- @GetMapping, @PostMapping, @PutMapping, @DeleteMapping
- @RequestMapping with method specification
- Count total number of API interfaces found
- Validation:
- If no interfaces found, STOP and inform user:
```
未找到任何接口，无法生成接口文档。请确认：
1. 项目中是否存在 Controller 类
2. Controller 类中是否有 @GetMapping、@PostMapping 等注解的方法
3. 是否指定了正确的扫描路径
```
- If interfaces found, proceed to Step 2
Output: List of Controller classes and total number of interfaces found.
#### Step 2: Extract Interface Information
CRITICAL: For each interface, extract complete information including URL, method, parameters, and response.
For each API interface found, extract:
- Basic Information:
- Interface Name: Method name or description from annotation
- Request Method: GET, POST, PUT, DELETE, PATCH
- Request URL: Full path including class-level and method-level mappings
- Controller Class: Full class name with package
- Method Name: Java/Kotlin method name
- Request Information:
- Path Parameters: Parameters in URL path (e.g., /user/{id})
- Parameter name, type, required flag, description
- Query Parameters: Parameters in query string
- Parameter name, type, required flag, default value, description
- Request Body (for POST/PUT):
- Body type (JSON, Form-data, etc.)
- Field definitions: name, type, required flag, description
- Nested object structures
- Request Headers:
- Common headers: Authorization, Shop-Id, Tenant-Id
- Custom headers if any
- Response Information:
- Response Type: Return type of the method
- Response Structure:
- Standard response wrapper (e.g., R, ApiResponse)
- Data object structure
- Response Fields:
- Field name, type, description
- Nested object fields
- Response Examples: Generate example JSON responses
- Error Responses: Common error codes and messages
- Additional Information:
- Description: From @ApiOperation, @Operation, or method comments
- Tags: From @Api, @Tag annotations
- Deprecated: Check for @Deprecated annotation
- Security: Authentication/authorization requirements
Output: Structured data for each interface with all extracted information.
#### Step 3: Generate Documentation
CRITICAL: Generate documentation following the standard template format.
- Select Template Language:
- Ask user for preferred language: Chinese or English
- If not specified, detect from project context (code comments, package names, etc.)
- Available templates:
- Chinese: templates/接口文档模板.md
- English: templates/api-documentation-template-en.md
- Load Template:
- Load the appropriate template based on language selection
- Use it as the base structure
- Organize by Module:
- Group interfaces by Controller class or business module
- Create sections for each module
- Generate Interface List Table:
- For Chinese template: Create "接口一览表" with columns:
- 序号 (Sequence number)
- 接口地址 (Interface URL)
- 请求方式 (Request Method)
- 说明 (Description)
- 完成情况 (Status)
- For English template: Create "API Interface List" with columns:
- No. (Sequence number)
- Interface URL
- Method
- Description
- Status
- Generate Interface Definitions:
For each interface, generate:
- Interface Name: Clear, descriptive name
- Interface Address: Full URL with method
- Description:
- Corresponding Controller class and method
- Business functionality description
- Business rules if any
- Request Section:
- Method and URL
- Headers table
- Path Parameters table
- Query Parameters table
- Request Body (if applicable) with field definitions
- Response Section:
- Response structure description
- Response fields table
- Response example (JSON)
- Error response examples
- Add Standard Sections:
- For Chinese template:
- 统一响应结构: Standard response format
- 分页响应格式: Pagination response format
- 错误码约定: Error code conventions
- 请求头规范: Request header specifications
- 注意事项: Important notes
- For English template:
- Standard Response Structure: Standard response format
- Pagination Response Format: Pagination response format
- Error Code Conventions: Error code conventions
- Request Header Specifications: Request header specifications
- Important Notes: Important notes
- Format Documentation:
- Use proper Markdown formatting
- Ensure tables are properly formatted
- Include code blocks for JSON examples
- Add proper headings hierarchy
Output: Complete API documentation in Markdown format.
#### Step 4: Save Documentation
CRITICAL: Save documentation to the ./docs directory in the current project.
- Determine Output Path:
- Default: ./docs/api-documentation.md
- If multiple modules: ./docs/{module-name}-api-documentation.md
- Ask user if they want a custom filename
- Create Directory:
- Check if ./docs directory exists
- If not, create it automatically
- Save File:
- Write the generated documentation to the file
- Use UTF-8 encoding
- Ensure proper line endings
- Inform User:
- Tell user where the file was saved
- Show the file path
- Optionally display a preview of the documentation
Output: Documentation file saved to ./docs/api-documentation.md (or custom path).
Code Scanning Guidelines
#### Java/Spring Boot Projects
Controller Identification:
- Look for classes annotated with
@RestController or @Controller - Check for
@RequestMapping at class level - Common package patterns:
.controller., .web., .api.
Method Identification:
- @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping
- @RequestMapping(method = RequestMethod.GET) etc.
Parameter Extraction:
@PathVariable: Path parameters@RequestParam: Query parameters@RequestBody: Request body@RequestHeader: Request headers- Parameter types from method signature
Response Extraction:
- Return type from method signature
@ResponseBody annotation- Generic types (e.g.,
R, Page) - Response entity structure
#### Kotlin/Spring Boot Projects
Similar to Java, but check for:
- Kotlin data classes for request/response
- Nullable types (
String?, Int?) - Kotlin-specific annotations
Documentation Template Structure
The generated documentation follows this structure (available in both Chinese and English):
Chinese Template (templates/接口文档模板.md):
- 文档概览 (Document Overview)
- Version history table
- Responsibility table
- 接口一览表 (Interface List Table)
- Summary table of all interfaces
- 接口定义 (Interface Definitions)
- Detailed definition for each interface
- Request and Response sections
- Field definitions and examples
- 统一响应结构 (Standard Response Structure)
- Standard response format
- Pagination format
- Error codes
- 请求头规范 (Request Header Specifications)
- 注意事项 (Important Notes)
English Template (templates/api-documentation-template-en.md):
- Document Overview
- Version history table
- Responsibility table
- API Interface List
- Summary table of all interfaces
- Interface Definitions
- Detailed definition for each interface
- Request and Response sections
- Field definitions and examples
- Standard Response Structure
- Standard response format
- Pagination format
- Error codes
- Request Header Specifications
- Important Notes
Template Selection:
- Ask user for preferred language (Chinese/English)
- If not specified, detect from project context
- Both templates follow the same structure, only language differs
Best Practices
- Complete Information: Extract all available information from code, including annotations and comments
- Standard Format: Follow the template structure strictly
- Clear Descriptions: Use meaningful descriptions from code comments or annotations
- Examples: Include realistic response examples
- Error Handling: Document common error scenarios
- Grouping: Organize interfaces by module or Controller class
- Validation: Verify all extracted information is accurate
Reference Documentation
- templates/接口文档模板.md - Standard API documentation template (Chinese)
- templates/api-documentation-template-en.md - Standard API documentation template (English)
- Example:
examples/scan-and-generate-example.md - Complete workflow example showing how to scan and generate API documentation
|