Agent Skills: api-doc-generator

How to use this skill

Scan code for API endpoints, extract interface details, and generate standardized documentation. Do NOT trigger for generic documentation requests without explicit API/interface mention.

Workflow

1. Scan Code - Check current project or specified objects for Controller classes and API interfaces
2. Extract Information - Scan interfaces to collect request URL, method, parameters, and response information
3. Generate Documentation - Create API documentation following the standard template
4. 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.

1. 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

2. Scan for Controllers:

   • Search for Controller classes in the project
   • Identify all classes annotated with @RestController or @Controller
   • List all found Controller classes

3. 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

4. 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:

1. 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

2. 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

3. Response Information:

   • Response Type: Return type of the method
   • Response Structure:
     • Standard response wrapper (e.g., R<T>, ApiResponse<T>)
     • 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

4. 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.

1. 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

2. Load Template:

   • Load the appropriate template based on language selection
   • Use it as the base structure

3. Organize by Module:

   • Group interfaces by Controller class or business module
   • Create sections for each module

4. 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

5. 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

6. 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

7. 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.

1. 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

2. Create Directory:

   • Check if ./docs directory exists
   • If not, create it automatically

3. Save File:

   • Write the generated documentation to the file
   • Use UTF-8 encoding
   • Ensure proper line endings

4. 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<T>, Page<T>)
• 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

Templates and References

• templates/接口文档模板.md - Chinese API documentation template
• templates/api-documentation-template-en.md - English API documentation template
• examples/scan-and-generate-example.md - Complete workflow example

Ask user for preferred language (Chinese/English). If not specified, detect from project context.

Best Practices

1. Extract all available information from code annotations and comments
2. Follow the template structure strictly
3. Include realistic response examples with proper JSON formatting
4. Document common error scenarios and codes
5. Organize interfaces by module or Controller class

Keywords

api documentation, api docs, generate api docs, scan interfaces, REST API, 接口文档, API文档, 生成接口文档, 扫描接口