api-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

重要提示：仅当用户明确提及生成API文档、创建API文档、扫描接口或为API编写文档时，才可触发本技能。

当用户提及以下内容时，请务必使用本技能：

生成API文档（明确提到“API documentation”或“API docs”）
从代码创建API文档
扫描接口以生成文档
为REST API编写文档
生成接口文档 (explicitly mentions "接口文档")
扫描接口生成文档 (scan interfaces to generate documentation)
创建API文档 (create API documentation)

触发短语包括：

"生成接口文档" (generate API documentation) - 必须包含“接口文档”
"扫描接口生成文档" (scan interfaces to generate documentation)
"创建API文档" (create API documentation)
"为接口生成文档" (generate documentation for interfaces)
"接口文档生成" (API documentation generation)

请勿在以下场景触发本技能：

未提及API/接口的通用文档请求
生成代码注释
生成README文件
其他类型的文档（用户指南、技术规范等）
不含“接口”或“API”的“生成文档”请求（过于宽泛）

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.

重要提示：仅当用户明确提及生成API文档时，才可触发本技能。对于无API上下文的通用文档请求，请勿触发。

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

本技能遵循系统化的四步工作流程：

扫描代码 - 检查当前项目或指定对象，查找Controller类和API接口
提取信息 - 扫描接口，收集请求URL、请求方法、参数和响应信息
生成文档 - 按照标准模板创建API文档
保存输出 - 将文档保存到当前项目的
```
./docs
```
目录

Step-by-Step Process

分步流程

Step 1: Scan Code for Interfaces

步骤1：扫描代码查找接口

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.

重要提示：在生成任何文档之前，必须先扫描代码以找到API接口。

确定扫描目标:
- 询问用户是要扫描整个项目还是特定的Controller类
- 如果未指定目标，则扫描整个项目查找Controller类
- 常见的Controller模式:
  - Java:
```
@RestController
```
    、带有
```
@RequestMapping
```
    的
```
@Controller
```
  - Spring Boot:
```
controller
```
    或
```
web
```
    包下的类
  - 以
```
Controller.java
```
    或
```
Controller.kt
```
    结尾的文件
扫描Controller类:
- 在项目中搜索Controller类
- 识别所有带有
```
@RestController
```
  或
```
@Controller
```
  注解的类
- 列出所有找到的Controller类
检查接口:
- 对每个Controller类，扫描带有以下注解的方法:
  - ```
  @GetMapping
```
  、
```
  @PostMapping
```
  、
```
  @PutMapping
```
  、
```
  @DeleteMapping
```
- 指定了请求方法的
```
  @RequestMapping
```
- 统计找到的API接口总数

验证:

如果未找到任何接口，停止操作并告知用户:

未找到任何接口，无法生成接口文档。请确认：
1. 项目中是否存在 Controller 类
2. Controller 类中是否有 @GetMapping、@PostMapping 等注解的方法
3. 是否指定了正确的扫描路径

如果找到接口，则进入步骤2

输出: 找到的Controller类列表和接口总数。

Step 2: Extract Interface Information

步骤2：提取接口信息

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

重要提示：对于每个接口，提取完整的信息，包括URL、请求方法、参数和响应。

对于每个找到的API接口，提取以下信息:

基础信息:
- 接口名称: 注解中的方法名或描述
- 请求方法: GET、POST、PUT、DELETE、PATCH
- 请求URL: 包含类级别和方法级别映射的完整路径
- Controller类: 带包名的完整类名
- 方法名: Java/Kotlin方法名
请求信息:
- 路径参数: URL路径中的参数（例如：
```
/user/{id}
```
  ）
  - 参数名、类型、是否必填、描述
- 查询参数: 查询字符串中的参数
  - 参数名、类型、是否必填、默认值、描述
- 请求体（适用于POST/PUT请求）:
  - 请求体类型（JSON、Form-data等）
  - 字段定义：名称、类型、是否必填、描述
  - 嵌套对象结构
- 请求头:
  - 常见请求头：Authorization、Shop-Id、Tenant-Id
  - 自定义请求头（如果有）
响应信息:
- 响应类型: 方法的返回类型
- 响应结构:
  - 标准响应包装类（例如：
```
R<T>
```
    、
```
ApiResponse<T>
```
    ）
  - 数据对象结构
- 响应字段:
  - 字段名、类型、描述
  - 嵌套对象字段
- 响应示例: 生成JSON格式的响应示例
- 错误响应: 常见错误码和错误信息
附加信息:
- 描述: 来自
```
@ApiOperation
```
  、
```
@Operation
```
  或方法注释
- 标签: 来自
```
@Api
```
  、
```
@Tag
```
  注解
- 是否废弃: 检查是否带有
```
@Deprecated
```
  注解
- 安全要求: 身份验证/授权要求

输出: 每个接口的结构化数据，包含所有提取的信息。

Step 3: Generate Documentation

步骤3：生成文档

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.

重要提示：按照标准模板格式生成文档。

选择模板语言:
- 询问用户偏好的语言：中文或英文
- 如果未指定，则根据项目上下文（代码注释、包名等）自动检测
- 可用模板:
  - 中文:
```
templates/接口文档模板.md
```
  - 英文:
```
templates/api-documentation-template-en.md
```
加载模板:
- 根据选择的语言加载对应的模板
- 将其作为基础结构
按模块组织:
- 按Controller类或业务模块对接口进行分组
- 为每个模块创建章节
生成接口一览表:
- 中文模板：创建“接口一览表”，包含以下列:
  - 序号
  - 接口地址
  - 请求方式
  - 说明
  - 完成情况
- 英文模板：创建“API Interface List”，包含以下列:
  - No.
  - Interface URL
  - Method
  - Description
  - Status
生成接口定义: 对于每个接口，生成以下内容:
- 接口名称: 清晰、具有描述性的名称
- 接口地址: 带请求方法的完整URL
- 描述:
  - 对应的Controller类和方法
  - 业务功能描述
  - 业务规则（如果有）
- 请求部分:
  - 请求方法和URL
  - 请求头表格
  - 路径参数表格
  - 查询参数表格
  - 请求体（如果适用）及字段定义
- 响应部分:
  - 响应结构描述
  - 响应字段表格
  - 响应示例（JSON格式）
  - 错误响应示例
添加标准章节:
- 中文模板:
  - 统一响应结构: 标准响应格式
  - 分页响应格式: 分页响应格式
  - 错误码约定: 错误码规则
  - 请求头规范: 请求头标准
  - 注意事项: 重要说明
- 英文模板:
  - Standard Response Structure: 标准响应格式
  - Pagination Response Format: 分页响应格式
  - Error Code Conventions: 错误码规则
  - Request Header Specifications: 请求头标准
  - Important Notes: 重要说明
格式化文档:
- 使用正确的Markdown格式
- 确保表格格式正确
- 为JSON示例添加代码块
- 设置合适的标题层级

输出: Markdown格式的完整API文档。

Step 4: Save Documentation

步骤4：保存文档

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

重要提示：将文档保存到当前项目的
./docs
目录。

确定输出路径:
- 默认路径:
```
./docs/api-documentation.md
```
- 如果是多模块项目:
```
./docs/{module-name}-api-documentation.md
```
- 询问用户是否需要自定义文件名
创建目录:
- 检查
```
./docs
```
  目录是否存在
- 如果不存在，则自动创建
保存文件:
- 将生成的文档写入文件
- 使用UTF-8编码
- 确保换行符格式正确
告知用户:
- 告知用户文件的保存位置
- 显示文件路径
- 可选：展示文档的预览内容

输出: 文档文件已保存到

./docs/api-documentation.md

（或自定义路径）。

Code Scanning Guidelines

代码扫描指南

Java/Spring Boot Projects

Java/Spring Boot项目

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

Controller类识别:

查找带有
```
@RestController
```
或
```
@Controller
```
注解的类
检查类级别是否带有
```
@RequestMapping
```
注解
常见包模式:
```
*.controller.*
```
、
```
*.web.*
```
、
```
*.api.*
```

方法识别:

带有以下注解的方法:

@GetMapping

、

@PostMapping

、

@PutMapping

、

@DeleteMapping

、

@PatchMapping

@RequestMapping(method = RequestMethod.GET)

等

参数提取:

```
@PathVariable
```
: 路径参数
```
@RequestParam
```
: 查询参数
```
@RequestBody
```
: 请求体
```
@RequestHeader
```
: 请求头
方法签名中的参数类型

响应提取:

方法签名中的返回类型
```
@ResponseBody
```
注解
泛型类型（例如：
```
R<T>
```
、
```
Page<T>
```
）
响应实体结构

Kotlin/Spring Boot Projects

Kotlin/Spring Boot项目

Similar to Java, but check for:

Kotlin data classes for request/response
Nullable types (
```
String?
```
,
```
Int?
```
)
Kotlin-specific annotations

与Java项目类似，但需注意:

请求/响应使用Kotlin数据类
可空类型（
```
String?
```
、
```
Int?
```
）
Kotlin专属注解

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

生成的文档遵循以下结构（支持中文和英文）:

中文模板 (

templates/接口文档模板.md

文档概览
- 版本历史表格
- 责任分工表格
接口一览表
- 所有接口的汇总表格
接口定义
- 每个接口的详细定义
- 请求和响应部分
- 字段定义和示例
统一响应结构
- 标准响应格式
- 分页格式
- 错误码
请求头规范
注意事项

英文模板 (

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

模板选择:

询问用户偏好的语言（中文/英文）
如果未指定，则根据项目上下文自动检测
两个模板结构一致，仅语言不同

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

信息完整: 从代码中提取所有可用信息，包括注解和注释
格式标准: 严格遵循模板结构
描述清晰: 使用代码注释或注解中有意义的描述
示例真实: 包含贴近实际的响应示例
错误处理: 记录常见错误场景
合理分组: 按模块或Controller类组织接口
验证准确: 确保所有提取的信息准确无误

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

模板:
- ```
templates/接口文档模板.md
```
  - 标准API文档模板（中文）
- ```
templates/api-documentation-template-en.md
```
  - 标准API文档模板（英文）
示例:
```
examples/scan-and-generate-example.md
```
- 完整工作流示例，展示如何扫描并生成API文档

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.

英文关键词: 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

中文关键词: 接口文档, API文档, 生成接口文档, 创建接口文档, 扫描接口, 接口文档生成, API文档生成, 接口文档生成器, 扫描Controller, 提取接口信息, 接口文档模板

重要提示: 所有关键词必须包含“接口文档”或“API”，以避免误触发。不含“接口”或“API”的通用术语如“生成文档”，请勿触发本技能。