When to use this skill
CRITICAL: This skill should ONLY be triggered when the user explicitly mentions generating API documentation, creating API docs, scanning interfaces, or documenting APIs.
ALWAYS use this skill when the user mentions:
Generating API documentation (explicitly mentions "API documentation" or "API docs") Creating API documentation from code Scanning interfaces to generate documentation Documenting REST APIs 生成接口文档 (explicitly mentions "接口文档") 扫描接口生成文档 (scan interfaces to generate documentation) 创建API文档 (create API documentation)
Trigger phrases include:
"生成接口文档" (generate API documentation) - must include "接口文档" "扫描接口生成文档" (scan interfaces to generate documentation) "创建API文档" (create API documentation) "为接口生成文档" (generate documentation for interfaces) "接口文档生成" (API documentation generation)
DO NOT trigger this skill for:
Generic documentation requests without mentioning API/interfaces Code comments generation README file generation Other types of documentation (user guides, technical specs, etc.) "生成文档" without "接口" or "API" (too generic) How to use this skill
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
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:
Methods annotated with: @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
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: 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 Keywords
English keywords: api documentation, api docs, generate api documentation, create api docs, scan interfaces, document apis, rest api documentation, interface documentation, api doc generator, scan controllers, extract api information
Chinese keywords (中文关键词): 接口文档, API文档, 生成接口文档, 创建接口文档, 扫描接口, 接口文档生成, API文档生成, 接口文档生成器, 扫描Controller, 提取接口信息, 接口文档模板
IMPORTANT: All keywords must include "接口文档" (API documentation) or "API" to avoid false triggers. Generic terms like "生成文档" (generate documentation) without "接口" or "API" should NOT trigger this skill.