api-doc-generator（API DOC 生成器）

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:

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

1. Scan for Controllers:

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

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

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

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

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

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

1. Load Template:

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

1. Organize by Module:

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

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

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

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

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

1. Create Directory:

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

1. Save File:

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

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

Documentation Template Structure

The generated documentation follows this structure (available in both Chinese and English):

Chinese Template (templates/接口文档模板.md):

1. 文档概览 (Document Overview)

- Version history table - Responsibility table

1. 接口一览表 (Interface List Table)

- Summary table of all interfaces

1. 接口定义 (Interface Definitions)

- Detailed definition for each interface - Request and Response sections - Field definitions and examples

1. 统一响应结构 (Standard Response Structure)

- Standard response format - Pagination format - Error codes

1. 请求头规范 (Request Header Specifications)
2. 注意事项 (Important Notes)

English Template (templates/api-documentation-template-en.md):

1. Document Overview

- Version history table - Responsibility table

1. API Interface List

- Summary table of all interfaces

1. Interface Definitions

- Detailed definition for each interface - Request and Response sections - Field definitions and examples

1. Standard Response Structure

- Standard response format - Pagination format - Error codes

1. Request Header Specifications
2. 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

1. Complete Information: Extract all available information from code, including annotations and comments
2. Standard Format: Follow the template structure strictly
3. Clear Descriptions: Use meaningful descriptions from code comments or annotations
4. Examples: Include realistic response examples
5. Error Handling: Document common error scenarios
6. Grouping: Organize interfaces by module or Controller class
7. 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.