doc-generator skill 是 Claude Code 提供的自动化 API 文档生成工具，能够从源代码中一键提取接口信息，输出标准化的 OpenAPI/Swagger 规范、SDK 示例、错误码参考等文档内容。无论是初次编写 API 文档，还是持续维护接口说明，都能极大提升效率和一致性。本文将详细介绍 doc-generator skill 的核心功能、标准输出结构、generate-docs.py 的使用流程，以及常见问题解答，帮助开发者快速掌握 API 文档自动化的最佳实践。

doc-generator skill：从源代码自动生成 API 文档

在实际开发中，API 文档的缺失或滞后常常成为团队协作和对外集成的最大障碍。doc-generator skill 正是为了解决“有代码没文档”这一痛点而设计。它可以自动分析源代码，生成结构化、易读且可直接集成的 API 文档，包括 OpenAPI/Swagger 规范、SDK 使用示例、错误码参考、认证说明等内容。无论你是 API 开发者还是维护者，都可以通过一键操作快速获得高质量的文档输出。

本指南将带你系统了解 doc-generator skill 的功能定位、文档结构标准，以及核心脚本 generate-docs.py 的使用方法。如果你还不熟悉 Claude Code 的整体架构，建议先阅读Claude Code 完全入门：从安装到掌握核心功能。

---

一、doc-generator skill 能做什么？

doc-generator skill 是 Claude Code Skills 体系中的一员，专门用于自动化生成 API 文档。它的核心能力包括：

• 自动提取 API 接口信息：从源代码（如 Python 函数）自动识别接口、参数、返回值等关键信息。
• 输出标准化文档结构：支持 OpenAPI/Swagger 规范，文档内容涵盖接口描述、参数表、响应示例、错误码、认证方式等。
• 生成多语言 SDK 示例：自动生成 cURL、JavaScript、Python 等主流语言的请求示例，方便开发者快速集成。
• 维护一致性与可追溯性：每次代码变更后可一键更新文档，降低手工维护成本，避免文档与实际接口不一致。

doc-generator skill 适用于创建新 API 文档、更新已有接口说明，或在用户提出“API 文档”、“接口文档”、“OpenAPI”、“Swagger”等需求时自动触发。

---

二、标准文档结构详解

自动生成的 API 文档采用结构化 Markdown 格式，便于阅读和后续集成。每个接口（endpoint）都按照如下标准格式输出：

## GET /api/v1/users/:id

### Description
Brief explanation of what this endpoint does

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

### Response

**200 Success**
```json
{
  "id": "usr_123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

404 Not Found

{
  "error": "USER_NOT_FOUND",
  "message": "User does not exist"
}

Examples

cURL

curl -X GET "https://api.example.com/api/v1/users/usr_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const user = await fetch('/api/v1/users/usr_123', {
  headers: { 'Authorization': 'Bearer token' }
}).then(r => r.json());

Python

response = requests.get(
    'https://api.example.com/api/v1/users/usr_123',
    headers={'Authorization': 'Bearer token'}
)
user = response.json()

**结构说明：**
- **接口标题**：包含 HTTP 方法和路径，如 `GET /api/v1/users/:id`
- **Description**：简要说明接口功能
- **Parameters**：参数表，列出名称、类型、是否必需、描述
- **Response**：典型响应示例，覆盖成功与错误场景
- **Examples**：多语言请求示例（cURL、JavaScript、Python 等）

这种结构不仅满足 OpenAPI/Swagger 的文档规范，也方便开发者和第三方快速理解和调用接口。

---

## 三、generate-docs.py 的作用与使用流程

doc-generator skill 的核心自动化能力由 `generate-docs.py` 脚本实现。它通过静态分析 Python 源代码，自动提取接口定义和文档信息，生成结构化的 Markdown 文档。

### 1. 脚本原理概览

- **AST 解析**：利用 Python 的 `ast` 模块遍历源代码，定位所有以 `get_`、`post_` 等命名的函数（即 API 端点）。
- **自动提取信息**：抓取函数名、参数、返回类型和 docstring（函数文档注释）。
- **标准化输出**：将提取的信息按统一格式渲染为 Markdown 文档。

### 2. 使用步骤

**Step 1：准备源代码**

确保你的 API 代码采用规范的函数命名和 docstring 注释。例如：

```python
def get_user(id: str) -> dict:
    """
    获取指定用户的信息

    参数:
      id (str): 用户ID

    返回:
      dict: 用户详细信息
    """
    # ...实际逻辑...

Step 2：运行 generate-docs.py

在命令行执行如下命令：

python3 generate-docs.py your_api_source.py > api-docs.md

• your_api_source.py：你的 API 源代码文件
• 输出将自动生成 api-docs.md，内容即为结构化 API 文档

Step 3：集成到开发流程

你可以将该脚本集成到 CI/CD 流程中，每次代码变更后自动更新 API 文档，确保文档始终与代码保持一致。

3. 输出示例

生成的 Markdown 文档如下：

# API Documentation

## get_user

获取指定用户的信息

**Parameters**: id

**Returns**: dict

---

你可以根据需要进一步扩展模板，或结合 Claude Code Skills 体系详解 实现更复杂的自动化文档管理。

---

四、最佳实践与注意事项

• 保持函数命名和注释规范：良好的代码注释和参数命名有助于 doc-generator skill 自动生成高质量文档。
• 多语言示例可自定义扩展：如需支持更多 SDK 示例，可在模板中按需添加。
• 结合 Hooks 与 Plugins 实现自动化：可通过 Claude Code Hooks 完全指南 实现文档自动更新，或用 Claude Code Plugins 集成到更大的开发工具链中。
• 适用于多种场景：不仅适合 RESTful API，也可扩展用于 GraphQL、RPC 等接口文档自动化。

---

FAQ

Q: doc-generator skill 支持哪些编程语言？
A: 当前 generate-docs.py 主要支持 Python 源代码的自动化文档生成，其他语言可通过自定义扩展实现。

Q: 如何让文档始终和代码保持同步？
A: 建议将 generate-docs.py 集成到 CI/CD 流程，每次代码提交后自动生成和发布最新文档。

Q: 可以生成 OpenAPI/Swagger 格式的文档吗？
A: 是的，doc-generator skill 支持输出 OpenAPI/Swagger 规范内容，并可扩展为 YAML/JSON 格式以便对接第三方工具。

---