Api doc generator

API Doc Generator

根据代码生成 API 文档，支持 REST API、GraphQL 及多种文档格式。

Generate API documentation from source code, supporting REST APIs, GraphQL, and various documentation formats.

When to Use

当用户请求以下操作时使用此 skill：

• 生成 API 文档 / Generate API documentation
• 创建接口文档 / Create interface documentation
• 编写 API 说明 / Write API descriptions
• 生成 OpenAPI/Swagger 规范 / Generate OpenAPI/Swagger specs

Instructions

分析步骤 / Analysis Steps

1. 识别 API 类型 - REST、GraphQL、RPC 等
2. 提取端点信息 - URL、方法、参数
3. 分析数据结构 - 请求/响应格式
4. 识别认证方式 - API Key、OAuth、JWT 等
5. 生成文档 - 按照标准格式输出

文档内容 / Documentation Content

每个 API 端点应包含：

• 端点路径 - URL 和 HTTP 方法
• 描述 - 功能说明
• 参数 - 路径参数、查询参数、请求体
• 响应 - 成功和错误响应示例
• 认证 - 认证要求

输出格式 / Output Formats

支持以下文档格式：

• Markdown（默认）- 使用 templates/api-doc.md 模板
• OpenAPI 3.0 YAML
• API Blueprint

Use templates/api-doc.md for Markdown output format.

标准模板 / Standard Template

## API 文档 / API Documentation

### 端点概览 / Endpoint Overview

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/resource | 获取资源列表 |

### 详细说明 / Details

#### [方法] /path

**描述**: ...

**请求参数**:
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|

**请求示例**:
```json
{}

响应示例:

{}

## Examples

### 输入 / Input

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int) -> User:
    """Get a user by ID."""
    if user_id <= 0:
        raise HTTPException(status_code=404, detail="User not found")
    return User(id=user_id, name="John", email="[email protected]")

@app.post("/users")
async def create_user(user: User) -> User:
    """Create a new user."""
    return user

输出 / Output

API 文档

端点概览

方法	路径	描述
GET	/users/{user_id}	根据 ID 获取用户信息
POST	/users	创建新用户

---

GET /users/{user_id}

描述: 根据用户 ID 获取用户信息

路径参数:

参数	类型	必需	描述
user_id	integer	✅	用户唯一标识符

响应 200 - 成功:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}

响应 404 - 未找到:

{
  "detail": "User not found"
}

---

POST /users

描述: 创建新用户

请求体:

字段	类型	必需	描述
id	integer	✅	用户 ID
name	string	✅	用户姓名
email	string	✅	用户邮箱

请求示例:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}

响应 200 - 成功:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}