ClawHub

API文档生成器

Data & APIs

后端写完接口最烦的就是写文档。丢代码或接口定义进来，自动生成OpenAPI 3.0/Swagger标准文档，附带SDK示例代码和Mock配置。再也不是「接口文档在老王的脑子里」这种状态了。 触发词：API文档、接口文档、生成API文档、Swagger文档、OpenAPI文档、REST API文档、GraphQL文档、WebSocket文档、接口规范、API规范、生成接口文档、接口说明、endpoints文档、API reference、SDK文档 排除：产品需求文档(用prd-generator)、技术架构文档(用technical-solution)、用户使用手册、数据库设计文档(用database-schema-designer) 上下文条件：用户提供代码/URL/OpenAPI文件/接口描述

Install

openclaw skills install qqyougit-api-doc-generator

API文档生成器 📋 v1.4.0

核心流程（8 Steps）

Step 1: API信息解析 🔍 输入识别

支持的输入格式：

格式识别方式优先级
OpenAPI YAML/JSON文件后缀/.yaml/.json★★★★★
代码框架特征关键词★★★★☆
URL链接HTTP/HTTPS前缀★★★☆☆
手动描述自然语言接口说明★★☆☆☆

代码框架识别：

Python:
- Flask: @app.route, @app.endpoint
- FastAPI: @app.get, @router
- Django: path(), urlpatterns
- Tornado: @route, RequestHandler

JavaScript:
- Express: app.get/post/put/delete
- Koa: router.get/post
- NestJS: @Controller, @Get

Go:
- Gin: router.GET/POST
- Echo: e.GET/e.POST
- Fiber: app.Get/app.Post

Java:
- Spring: @RequestMapping, @GetMapping
- Spring Boot: @RestController

解析检查清单：

  • 路由定义完整（URL路径）
  • HTTP方法正确（GET/POST/PUT/DELETE/PATCH）
  • 参数定义（路径/查询/请求体）
  • 响应格式定义
  • 认证方式识别

Step 2: 接口详情提取 📦 字段定义

参数分类：

Path参数: /users/{id} → id为路径参数
Query参数: /users?page=1&size=10 → page,size为查询参数
Header参数: Authorization: Bearer xxx → 认证header
Body参数: POST请求体 → JSON Schema定义
Cookie参数: session_id=xxx → Cookie参数

数据类型规范：

JSON Type格式约束示例
string-"hello"
stringemail"user@example.com"
stringdate"2024-01-01"
stringdate-time"2024-01-01T12:00:00Z"
stringuri"https://api.example.com"
stringuuid"550e8400-e29b..."
integerint32/int64123
numberfloat/double12.34
boolean-true/false
array-[1,2,3]
object-{"key":"value"}

必填vs可选：

  • required: 必填字段
  • nullable: 可为null
  • default: 默认值

Step 3: 响应模式定义 📤 状态码体系

HTTP状态码规范：

状态码含义使用场景
200OK成功响应
201Created资源创建成功
204No Content删除成功（无body）
400Bad Request参数错误
401Unauthorized未认证
403Forbidden无权限
404Not Found资源不存在
409Conflict资源冲突
422Unprocessable Entity验证失败
429Too Many Requests请求过于频繁
500Internal Server Error服务器错误
503Service Unavailable服务不可用

响应体结构：

// 成功响应
{
  "code": 0,
  "message": "success",
  "data": { ... }
}

// 错误响应
{
  "code": 40001,
  "message": "参数错误",
  "data": null
}

Step 4: 认证与安全配置 🔐 安全规范

认证方式：

方式适用场景Header格式
Bearer TokenAPI Key / JWTAuthorization: Bearer xxx
Basic Auth用户名密码Authorization: Basic base64
API Key静态密钥X-API-Key: xxx
OAuth 2.0第三方授权-

安全扫描清单：

  • 敏感参数脱敏（password/secret/token）
  • 脱敏字段不能出现在日志中
  • 请求体大小限制
  • 速率限制说明（Rate Limit）
  • CORS配置说明

安全Headers：

X-Request-ID: 请求追踪ID
X-Rate-Limit-Limit: 请求限额
X-Rate-Limit-Remaining: 剩余请求数
X-Rate-Limit-Reset: 重置时间戳

Step 5: OpenAPI 3.0规范生成 📄 标准输出

文件结构：

openapi: 3.0.3
info:
  title: API名称
  version: 版本号
  description: API描述
servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://api-staging.example.com/v1
    description: 测试环境
paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: getUsers
      tags:
        - 用户管理
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
components:
  schemas:
    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Step 6: SDK示例生成 💻 多语言示例

Python SDK示例：

import requests

class ExampleAPI:
    BASE_URL = "https://api.example.com/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })
    
    def get_users(self, page: int = 1, size: int = 20) -> dict:
        """获取用户列表"""
        response = self.session.get(
            f"{self.BASE_URL}/users",
            params={"page": page, "size": size}
        )
        response.raise_for_status()
        return response.json()
    
    def create_user(self, name: str, email: str) -> dict:
        """创建用户"""
        response = self.session.post(
            f"{self.BASE_URL}/users",
            json={"name": name, "email": email}
        )
        response.raise_for_status()
        return response.json()

# 使用示例
api = ExampleAPI(api_key="your_api_key")
users = api.get_users(page=1, size=10)

JavaScript SDK示例：

class ExampleAPI {
  constructor(apiKey) {
    this.baseURL = 'https://api.example.com/v1';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async getUsers(page = 1, size = 20) {
    const response = await fetch(
      `${this.baseURL}/users?page=${page}&size=${size}`,
      { headers: this.headers }
    );
    if (!response.ok) throw new Error(response.statusText);
    return response.json();
  }

  async createUser(name, email) {
    const response = await fetch(`${this.baseURL}/users`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ name, email })
    });
    if (!response.ok) throw new Error(response.statusText);
    return response.json();
  }
}

// 使用示例
const api = new ExampleAPI('your_api_key');
const users = await api.getUsers(1, 10);

cURL示例：

# 获取用户列表
curl -X GET "https://api.example.com/v1/users?page=1&size=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# 创建用户
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"zhangsan@example.com"}'

Step 7: Mock服务器配置 🎭 测试配置

Mock配置模板：

// mock-server.js
const express = require('express');
const app = express();
app.use(express.json());

// 用户列表Mock
app.get('/v1/users', (req, res) => {
  res.json({
    code: 0,
    message: 'success',
    data: {
      users: [
        { id: 1, name: '张三', email: 'zhangsan@example.com' },
        { id: 2, name: '李四', email: 'lisi@example.com' }
      ],
      pagination: {
        page: 1,
        size: 20,
        total: 100
      }
    }
  });
});

// 创建用户Mock
app.post('/v1/users', (req, res) => {
  const { name, email } = req.body;
  res.status(201).json({
    code: 0,
    message: 'success',
    data: { id: Math.floor(Math.random() * 1000), name, email }
  });
});

app.listen(3000, () => console.log('Mock server running on :3000'));

Mock响应规则：

  • 正常场景：返回模拟数据
  • 错误场景：返回错误码和消息
  • 延迟模拟：可配置网络延迟（ms）
  • 随机失败：可模拟5xx错误

Step 8: 集成测试用例生成 🧪 测试覆盖

测试用例模板：

// api.test.js
const axios = require('axios');

describe('用户管理API测试', () => {
  const api = axios.create({
    baseURL: 'https://api.example.com/v1',
    headers: { Authorization: 'Bearer test_token' }
  });

  describe('GET /users', () => {
    test('正常获取用户列表', async () => {
      const res = await api.get('/users', {
        params: { page: 1, size: 10 }
      });
      expect(res.status).toBe(200);
      expect(res.data.code).toBe(0);
      expect(res.data.data.users).toBeInstanceOf(Array);
    });

    test('分页参数验证', async () => {
      const res = await api.get('/users', {
        params: { page: 999, size: 0 }
      });
      expect(res.data.code).toBe(400);
    });
  });

  describe('POST /users', () => {
    test('正常创建用户', async () => {
      const res = await api.post('/users', {
        name: '测试用户',
        email: 'test@example.com'
      });
      expect(res.status).toBe(201);
      expect(res.data.data.id).toBeDefined();
    });

    test('邮箱格式错误', async () => {
      try {
        await api.post('/users', {
          name: '测试',
          email: 'invalid-email'
        });
      } catch (e) {
        expect(e.response.status).toBe(400);
      }
    });
  });
});

输出模板

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 API文档 | {API名称} | v{版本}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 概述
| 属性 | 值 |
|------|-----|
| API名称 | {name} |
| 版本 | v{version} |
| Base URL | {base_url} |
| 认证方式 | {Bearer Token/API Key/...} |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |

## 快速开始

### 1. 获取API Key
[申请流程说明]

### 2. 安装SDK
```bash
pip install example-api-sdk    # Python
npm install example-api-sdk   # JavaScript

3. 首次调用

from example_api import Client
client = Client(api_key="YOUR_API_KEY")
result = client.get_users()

认证说明

[认证方式详细说明] [Token获取/刷新流程]

接口文档

GET /users

获取用户列表

请求参数

参数名类型位置必填说明
pageintquery否页码，默认1
sizeintquery否每页数量，默认20

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "users": [...],
    "pagination": {...}
  }
}

POST /users

创建用户

请求参数

参数名类型必填说明
namestring是用户名
emailstring是邮箱

请求示例

{
  "name": "张三",
  "email": "zhangsan@example.com"
}

错误码

错误码HTTP状态码说明解决方案
0200成功-
40001400参数错误检查请求参数
40101401认证失败检查API Key
40301403无权限申请权限
40401404资源不存在检查ID
42901429请求过于频繁降低频率

SDK示例

Python

[完整SDK代码]

JavaScript

[完整SDK代码]

cURL

[完整cURL命令]

Mock服务

npm install -g mock-server
mock-server start --port 3000 --spec ./api_doc.yaml

集成测试

npm test

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 输出文件：

  • api_doc.md # Markdown格式文档
  • api_doc.yaml # OpenAPI 3.0规范
  • api_doc.html # HTML可阅读文档
  • sdk_python.py # Python SDK
  • sdk_javascript.js # JavaScript SDK
  • sdk_examples.sh # cURL示例
  • mock_server.js # Mock服务
  • api_tests.js # 测试用例 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

## 正向示例 ✅

### 示例1：FastAPI代码生成完整文档

输入：

from fastapi import FastAPI
app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

输出：完整OpenAPI YAML + Markdown文档 + Python SDK


### 示例2：URL链接解析生成文档

输入：https://api.github.com/users/{username}

输出：

  • GitHub用户API完整文档
  • 自动识别认证方式（Bearer Token）
  • 生成响应字段说明
  • 错误码映射（404/403等）

---

## 反向示例 ❌

### 示例3：遗漏认证信息

问题：只生成接口，遗漏认证header

正确做法：

  • 每个接口自动添加认证参数
  • 敏感字段自动标记
  • 提供测试Token说明

### 示例4：状态码不完整

问题：只有200成功响应

正确做法：

  • 覆盖所有常见状态码
  • 每种错误提供code和message
  • 错误场景给出解决方案

---

## 边界场景 🌐

### 边界1：分页参数处理

场景：大量数据分页查询 文档需包含：

  • 页码分页：page/size
  • 游标分页：cursor/limit
  • 偏移分页：offset/limit
  • 分页响应结构

### 边界2：文件上传接口

特殊处理：

  • Content-Type: multipart/form-data
  • 文件大小限制
  • 支持格式列表
  • 上传进度说明

### 边界3：WebSocket接口

文档需包含：

  • 连接建立：wss://...
  • 心跳机制
  • 消息格式
  • 断线重连策略
  • 错误码体系

### 边界4：超时时重试策略

重试规范：

  • 超时时间：默认30s
  • 最大重试：3次
  • 指数退避：1s → 2s → 4s
  • 重试头：X-Retry-Count

### 边界5：版本迁移指南

v1 → v2迁移：

  • 废弃时间线
  • breaking changes清单
  • 迁移步骤
  • 兼容模式说明

---

## GraphQL支持 📊

**输出扩展**：
```graphql
# GraphQL Schema

type Query {
  users(page: Int, size: Int): UserConnection!
  user(id: ID!): User
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

type User {
  id: ID!
  name: String!
  email: String!
}

input CreateUserInput {
  name: String!
  email: String!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

质量检查清单 ✅

文档发布前检查：

  • 所有接口都有完整参数说明
  • 响应格式示例可运行
  • 错误码覆盖完整
  • SDK代码无语法错误
  • 认证方式清晰可操作
  • Mock服务可用
  • 测试用例覆盖主流程
  • 版本号正确

Output Language

中文文档，代码示例英文注释

Anti-rationalization

借口正确做法
"认证方式代码里没写，跳过不标了"必须显式标注认证方式（Bearer/Basic/API Key/OAuth），无认证也要注明"该接口无需认证"
"响应只写200成功的格式就行"必须覆盖至少4种HTTP状态码（200/400/401/404），每种错误附带错误码code和message
"SDK示例写一个语言就够了"必须提供至少3种语言示例（Python/JavaScript/cURL），每段代码必须可直接运行
"参数类型写string或int就行了"每个参数必须标注完整类型信息：类型+格式+约束（如string/email/maxLength），必填/可选必须明确
"Mock服务用户自己搭就行，不用提供"必须提供可运行的Mock服务代码，覆盖正常和异常场景
"错误码在业务层定义，不用列全"必须提供完整错误码映射表，每个错误码附带HTTP状态码、含义和解决方案
"分页/限流这些边界场景不用写"分页参数、速率限制、超时重试策略必须在文档中显式说明，即使是默认值也要标注
More in Data & APIs