api-document-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Documentation Generator

API文档生成工具

This skill automatically generates OpenAPI-compliant documentation from code files. It parses interface definitions, API endpoints, and related information to create comprehensive, readable API documentation that follows OpenAPI specification standards.

该工具可从代码文件中自动生成符合OpenAPI规范的文档。它会解析接口定义、API端点及相关信息，创建遵循OpenAPI规范标准的全面、易读的API文档。

Capabilities

功能特性

File Parsing: Parse interface/API information from files or directories
OpenAPI Compliance: Generate documentation that complies with OpenAPI specification (https://swagger.io/specification/)
Timestamp Management: Automatically include timestamps in documentation files
Directory Scanning: Process multiple files in a directory structure
Validation: Validate generated documentation against OpenAPI standards
Multiple Formats: Support for various code file types (Python, JavaScript, TypeScript, etc.)

文件解析：从文件或目录中解析接口/API信息
OpenAPI合规性：生成符合OpenAPI规范的文档（https://swagger.io/specification/）
时间戳管理：自动在文档文件中包含时间戳
目录扫描：处理目录结构中的多个文件
验证功能：根据OpenAPI标准验证生成的文档
多格式支持：支持多种代码文件类型（Python、JavaScript、TypeScript等）

Input Requirements

输入要求

File or directory path: Path to the file or directory containing API/interface definitions
Supported file types: Python (.py), JavaScript (.js), TypeScript (.ts), JSON (.json), YAML (.yaml, .yml)
Optional parameters:
- ```
output_format
```
  : Format for documentation (default: markdown)
- ```
include_examples
```
  : Whether to include example requests/responses (default: true)
- ```
validate_openapi
```
  : Validate against OpenAPI specification (default: true)

文件或目录路径：包含API/接口定义的文件或目录路径
支持的文件类型：Python（.py）、JavaScript（.js）、TypeScript（.ts）、JSON（.json）、YAML（.yaml、.yml）
可选参数:
- ```
output_format
```
  : 文档格式（默认：markdown）
- ```
include_examples
```
  : 是否包含请求/响应示例（默认：true）
- ```
validate_openapi
```
  : 是否根据OpenAPI规范验证（默认：true）

Output Formats

输出格式

Primary output: Markdown file with timestamp format:
```
YYYY-MM-DD_HH-MM-SS.md
```
Location: Saved to
```
current_repository/.claude/api_doc/
```
directory
Content: OpenAPI-compliant documentation with:
- API title and description
- Endpoint definitions
- Request/response schemas
- Authentication information
- Example usage
- Error codes and responses
- Timestamp and generation metadata

主要输出：带时间戳格式的Markdown文件：
```
YYYY-MM-DD_HH-MM-SS.md
```
存储位置：保存至
```
current_repository/.claude/api_doc/
```
目录
内容：符合OpenAPI规范的文档包含：
- API标题与描述
- 端点定义
- 请求/响应模式
- 认证信息
- 使用示例
- 错误码与响应
- 时间戳与生成元数据

How to Use

使用方法

"Generate API documentation from the

src/api/

directory" "Parse this Python file and create OpenAPI documentation" "Create API documentation for the endpoints in this TypeScript file"

"从

src/api/

目录生成API文档" "解析此Python文件并创建OpenAPI文档" "为此TypeScript文件中的端点创建API文档"

Scripts

脚本文件

```
api_parser.py
```
: Main module for parsing API information from files
```
openapi_generator.py
```
: Generates OpenAPI-compliant documentation
```
file_handler.py
```
: Handles file operations and directory scanning

```
api_parser.py
```
: 从文件中解析API信息的主模块
```
openapi_generator.py
```
: 生成符合OpenAPI规范的文档
```
file_handler.py
```
: 处理文件操作与目录扫描

Best Practices

最佳实践

File Organization: Keep API-related files in structured directories
Clear Naming: Use descriptive names for endpoints and parameters
Consistent Formatting: Follow consistent code formatting for better parsing
Comments: Include clear comments in code for better documentation generation
Validation: Always validate generated documentation against OpenAPI standards

文件组织：将API相关文件存放在结构化目录中
清晰命名：为端点和参数使用描述性名称
格式一致：遵循统一的代码格式以提升解析效果
代码注释：在代码中添加清晰的注释以优化文档生成效果
验证检查：始终根据OpenAPI标准验证生成的文档

Limitations

局限性

Requires properly formatted code with clear interface definitions
Complex nested structures may require manual review
Some framework-specific annotations may not be fully parsed
Generated documentation quality depends on source code clarity
Large directories may take longer to process

需要格式规范且接口定义清晰的代码
复杂的嵌套结构可能需要人工审核
部分框架特定的注解可能无法被完全解析
生成的文档质量取决于源代码的清晰度
大型目录的处理时间可能较长