chinese-interface-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

接口文档生成助手

Interface Documentation Generator Assistant

此技能为中文开发者自动分析代码中的接口定义（函数、类、模块、API端点等），提取中文注释和文档字符串，生成简洁清晰的中文接口文档。专注于内部文档、快速原型和团队协作场景，支持交互式选项选择。

区别于OpenAPI生成器：通用接口支持（非仅API）、中文优先、简单交互、无复杂规范验证。

This skill automatically analyzes interface definitions (functions, classes, modules, API endpoints, etc.) in code for Chinese developers, extracts Chinese comments and docstrings, and generates concise and clear Chinese interface documentation. Focused on internal documentation, rapid prototyping, and team collaboration scenarios, it supports interactive option selection.

Differences from OpenAPI generators: universal interface support (not just APIs), Chinese-first, simple interaction, no complex specification validation.

能力

Capabilities

接口分析：识别Python/JS代码中的函数、类方法、API端点等接口定义
中文文档提取：优先提取中文注释、docstring，支持简繁体中文
多格式输出：Markdown、HTML、JSON，支持REST/GraphQL/函数接口
交互选项：选择详细程度（简要/详细）、格式、包含示例
报告生成：一键生成完整中文接口报告，保存为时间戳文件
团队友好：简洁输出，便于中文团队审阅和协作

Interface Analysis: Identifies interface definitions such as functions, class methods, and API endpoints in Python/JS code
Chinese Document Extraction: Prioritizes extracting Chinese comments and docstrings, supports simplified and traditional Chinese
Multi-format Output: Markdown, HTML, JSON, supports REST/GraphQL/function interfaces
Interactive Options: Select detail level (brief/detailed), format, and whether to include examples
Report Generation: One-click generation of complete Chinese interface reports, saved as timestamped files
Team-friendly: Concise output, easy for Chinese teams to review and collaborate

输入要求

Input Requirements

代码内容：代码字符串、文件路径或目录（支持.py, .js, .ts）
语言类型：python（默认）、javascript、typescript
可选参数：
- ```
detail_level
```
  : 简要/详细 (default: 详细)
- ```
output_format
```
  : markdown/html/json (default: markdown)
- ```
include_examples
```
  : true/false (default: true)

示例输入：

json

{
  "code": "def 用户登录(user: str, pwd: str) -> bool:\n    '''用户登录接口\n    参数:\n    - user: 用户名\n    - pwd: 密码\n    返回: 登录成功True'''\n    pass",
  "lang": "python",
  "detail_level": "详细"
}

Code Content: Code strings, file paths, or directories (supports .py, .js, .ts)
Language Type: python (default), javascript, typescript
Optional Parameters:
- ```
detail_level
```
  : brief/detailed (default: detailed)
- ```
output_format
```
  : markdown/html/json (default: markdown)
- ```
include_examples
```
  : true/false (default: true)

Example Input:

json

{
  "code": "def 用户登录(user: str, pwd: str) -> bool:\n    '''用户登录接口\n    参数:\n    - user: 用户名\n    - pwd: 密码\n    返回: 登录成功True'''\n    pass",
  "lang": "python",
  "detail_level": "详细"
}

输出格式

Output Format

主要输出：中文Markdown报告，格式：
```
接口文档_YYYY-MM-DD_HH-MM-SS.md
```
保存位置：
```
.claude/interface_docs/
```
内容包括：
- 接口列表与签名
- 中文描述/参数/返回值
- 示例调用（若有）
- 错误码/异常处理
- 生成元数据

Main Output: Chinese Markdown report, format:
```
接口文档_YYYY-MM-DD_HH-MM-SS.md
```
Save Location:
```
.claude/interface_docs/
```
Content Includes:
- Interface list and signatures
- Chinese descriptions/parameters/return values
- Example calls (if available)
- Error codes/exception handling
- Generation metadata

如何使用

How to Use

“使用chinese-interface-doc-generator技能分析这个Python文件中的接口并生成中文文档”

“为这个函数生成简要中文接口文档，包括参数说明”

“提取这个JS模块的所有方法文档，用HTML格式输出”

"Use the chinese-interface-doc-generator skill to analyze interfaces in this Python file and generate Chinese documentation"

"Generate a brief Chinese interface document for this function, including parameter descriptions"

"Extract all method documentation from this JS module and output in HTML format"

脚本

Scripts

```
interface_analyzer.py
```
: 接口定义分析器，使用AST解析Python代码
```
chinese_doc_extractor.py
```
: 中文注释和docstring提取器，支持正则匹配中文
```
doc_formatter.py
```
: 文档格式化，支持Markdown/HTML/JSON
```
report_generator.py
```
: 完整报告生成器，整合分析结果并写入文件

```
interface_analyzer.py
```
: Interface definition analyzer, uses AST to parse Python code
```
chinese_doc_extractor.py
```
: Chinese comment and docstring extractor, supports regex matching of Chinese
```
doc_formatter.py
```
: Document formatter, supports Markdown/HTML/JSON
```
report_generator.py
```
: Complete report generator, integrates analysis results and writes to files

最佳实践

Best Practices

代码规范：使用中文docstring，便于自动提取
结构清晰：接口定义使用标准语法，避免嵌套过深
提供示例：代码中包含调用示例，提高文档质量
分模块分析：大型项目分目录处理，避免单次过载
审阅输出：自动生成后手动补充业务上下文

Code Standards: Use Chinese docstrings for easy automatic extraction
Clear Structure: Use standard syntax for interface definitions, avoid excessive nesting
Provide Examples: Include call examples in code to improve documentation quality
Module-wise Analysis: Process large projects by directories to avoid single overload
Review Output: Manually add business context after automatic generation

限制

Limitations

主要支持Python/JS/TS，复杂语言需手动调整
依赖代码注释质量，无注释时仅提取签名
非动态语言的二进制接口不支持
大型代码库建议分批处理

Mainly supports Python/JS/TS; complex languages require manual adjustments
Depends on code comment quality; only extracts signatures when there are no comments
Binary interfaces of non-dynamic languages are not supported
Large codebases are recommended to be processed in batches