api-documenter

API 文档生成器技能

根据代码自动生成 API 文档。

何时激活

• ✅ 添加或修改 API 端点
• ✅ 用户提到 API 文档、OpenAPI 或 Swagger
• ✅ 路由文件发生更改
• ✅ 控制器文件发生修改
• ✅ 需要编写文档

我会生成什么

OpenAPI 3.0 规范

• 端点描述
• 请求／响应架构
• 身份验证要求
• 示例负载
• 错误响应

支持的格式

• OpenAPI 3.0（JSON/YAML）
• Swagger 2.0
• API Blueprint
• RAML

示例

Express.js 端点

// You write:
/**
 * Get user by ID
 * @param {string} id - User ID
 * @returns {User} User object
 */
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);
});

// I auto-generate OpenAPI spec:
paths:
  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: "123"
                name: "John Doe"
                email: "[email protected]"
        '404':
          description: User not found

FastAPI 端点

# You write:
@app.get("/users/{user_id}")
def get_user(user_id: int) -> User:
    """Get user by ID"""
    return db.query(User).filter(User.id == user_id).first()

// I auto-generate:
paths:
  /users/{user_id}:
    get:
      summary: Get user by ID
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

完整的 OpenAPI 文档

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

servers:
  - url: https://api.example.com/v1

paths:
  /api/users:
    get:
      summary: List all users
      responses:
        '200':
          description: Users array
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

检测逻辑

框架检测

我可以自动识别以下框架：

• Express.js（Node.js）
• FastAPI（Python）
• Django REST（Python）
• Spring Boot（Java）
• Gin（Go）
• Rails（Ruby）

注释解析

我会从以下内容中提取文档：

• JSDoc 注释（/** */）
• Python 文档字符串
• JavaDoc
• 带装饰器的行内注释

文档增强

缺失的信息

// Your code:
app.post('/api/users', (req, res) => {
  User.create(req.body);
});

// I suggest additions:
/**
 * Create new user
 * @param {Object} req.body - User data
 * @param {string} req.body.name - User name (required)
 * @param {string} req.body.email - User email (required)
 * @returns {User} Created user
 * @throws {400} Invalid input
 * @throws {409} Email already exists
 */

生成示例

我会生成真实的示例：

{
  "id": "usr_1234567890",
  "name": "John Doe",
  "email": "[email protected]",
  "createdAt": "2025-10-24T10:30:00Z",
  "verified": true
}

与 @docs-writer 的关系

我（技能）： 根据代码自动生成 API 规范 @docs-writer（子 Agent）： 编写全面的用户指南和教程

工作流

1. 我生成 OpenAPI 规范
2. 你需要用户指南 → 调用 @docs-writer 子 Agent
3. 子 Agent 创建完整的文档站点

集成

与 Swagger UI 集成

// app.js
const swaggerUi = require('swagger-ui-express');
const spec = require('./openapi.json'); // Generated by skill

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));

与 Postman 集成

导出生成的 OpenAPI 规范：

# Import into Postman for API testing
File → Import → openapi.json

与文档站点集成

• Docusaurus：API 文档插件
• MkDocs：OpenAPI 插件
• Redoc：OpenAPI 渲染器
• Stoplight：API 设计平台

自定义

添加公司特定的文档规范：

cp -r ~/.claude/skills/documentation/api-documenter \
      ~/.claude/skills/documentation/company-api-documenter

# Edit to add:
# - Company API standards
# - Custom response formats
# - Internal schemas

沙盒兼容性

无需沙盒即可运行： ✅ 是 在沙盒中运行： ✅ 是

• 文件系统：写入 OpenAPI 文件
• 网络：无需网络
• 配置：无需配置

最佳实践

1. 保持注释更新——文档应与代码同步
2. 使用类型提示——TypeScript 和 Python 类型会有所帮助
3. 包含示例——提供真实场景中的请求／响应
4. 记录错误——列出所有可能的错误响应
5. 为 API 添加版本号——在端点中包含版本号

相关工具

• @docs-writer 子 Agent：用户指南和教程
• readme-updater 技能：保持 README 更新
• /docs-gen 命令：生成完整文档