api-doc-generator

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

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

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

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

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

   • Summary table of all interfaces

3. 接口定义 (Interface Definitions)

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

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

   • Standard response format
   • Pagination format
   • Error codes

5. 请求头规范 (Request Header Specifications)

6. 注意事项 (Important Notes)

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

1. Document Overview

   • Version history table
   • Responsibility table

2. API Interface List

   • Summary table of all interfaces

3. Interface Definitions

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

4. Standard Response Structure

   • Standard response format
   • Pagination format
   • Error codes

5. Request Header Specifications

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

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题