Back to Details

api-documenter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Documenter Skill

API Documenter Skill

Auto-generate API documentation from code.
从代码自动生成API文档。

When I Activate

触发场景

  • ✅ API endpoints added/modified
  • ✅ User mentions API docs, OpenAPI, or Swagger
  • ✅ Route files changed
  • ✅ Controller files modified
  • ✅ Documentation needed
  • ✅ API端点新增/修改
  • ✅ 用户提及API文档、OpenAPI或Swagger
  • ✅ 路由文件变更
  • ✅ 控制器文件修改
  • ✅ 需要生成文档

What I Generate

生成内容

OpenAPI 3.0 Specifications

OpenAPI 3.0 Specifications

  • Endpoint descriptions
  • Request/response schemas
  • Authentication requirements
  • Example payloads
  • Error responses
  • 端点描述
  • 请求/响应 schema
  • 认证要求
  • 示例请求体
  • 错误响应

Formats Supported

支持的格式

  • OpenAPI 3.0 (JSON/YAML)
  • Swagger 2.0
  • API Blueprint
  • RAML
  • OpenAPI 3.0 (JSON/YAML)
  • Swagger 2.0
  • API Blueprint
  • RAML

Examples

示例

Express.js Endpoint

Express.js Endpoint

javascript
// 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: "john@example.com"
        '404':
          description: User not found
javascript
// 你的代码：
/**
 * 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);
});

// 我自动生成的OpenAPI规范：
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: "john@example.com"
        '404':
          description: User not found

FastAPI Endpoint

FastAPI Endpoint

python
undefined
python
// 你的代码：
@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()

// 我自动生成的内容：
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'

You write:

完整OpenAPI文档

@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'
undefined
yaml
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

Complete OpenAPI Document

检测逻辑

—

框架检测

yaml
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)

Detection Logic

注释解析

Framework Detection

—
I recognize these frameworks automatically:
  • Express.js (Node.js)
  • FastAPI (Python)
  • Django REST (Python)
  • Spring Boot (Java)
  • Gin (Go)
  • Rails (Ruby)
我从以下注释中提取文档信息：
  • JSDoc comments (
    /** */
    )
  • Python docstrings
  • JavaDoc
  • 带装饰器的行内注释

Comment Parsing

文档增强

—

补充缺失信息

I extract documentation from:
  • JSDoc comments (
    /** */
    )
  • Python docstrings
  • JavaDoc
  • Inline comments with decorators
javascript
// 你的代码：
app.post('/api/users', (req, res) => {
  User.create(req.body);
});

// 我建议补充的注释：
/**
 * 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
 */

Documentation Enhancement

示例生成

Missing Information

—
javascript
// 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
 */
我会生成贴近真实场景的示例：
json
{
  "id": "usr_1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2025-10-24T10:30:00Z",
  "verified": true
}

Example Generation

与@docs-writer的关系

I generate realistic examples:
json
{
  "id": "usr_1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2025-10-24T10:30:00Z",
  "verified": true
}
我（Skill）： 从代码自动生成API规范 @docs-writer（子Agent）： 生成完整的用户指南和教程

Relationship with @docs-writer

工作流程

Me (Skill): Auto-generate API specs from code @docs-writer (Sub-Agent): Comprehensive user guides and tutorials
  1. 我生成OpenAPI规范
  2. 若需要用户指南 → 调用**@docs-writer**子Agent
  3. 子Agent创建完整的文档站点

Workflow

集成方式

—

与Swagger UI集成

  1. I generate OpenAPI spec
  2. You need user guide → Invoke @docs-writer sub-agent
  3. Sub-agent creates complete documentation site
javascript
// app.js
const swaggerUi = require('swagger-ui-express');
const spec = require('./openapi.json'); // 由本Skill生成

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

Integration

与Postman集成

With Swagger UI

—
javascript
// 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));
导出生成的OpenAPI规范：
bash
undefined

With Postman

导入到Postman中进行API测试

Export generated OpenAPI spec:
bash
undefined
File → Import → openapi.json
undefined

Import into Postman for API testing

与文档站点集成

File → Import → openapi.json
undefined
  • Docusaurus：API文档插件
  • MkDocs：OpenAPI插件
  • Redoc：OpenAPI渲染器
  • Stoplight：API设计平台

With Documentation Sites

自定义配置

  • Docusaurus: API docs plugin
  • MkDocs: OpenAPI plugin
  • Redoc: OpenAPI renderer
  • Stoplight: API design platform
添加公司专属的文档规范：
bash
cp -r ~/.claude/skills/documentation/api-documenter \
      ~/.claude/skills/documentation/company-api-documenter

Customization

编辑文件以添加：

—

- 公司API规范

—

- 自定义响应格式

—

- 内部schema

Add company-specific documentation standards:
bash
cp -r ~/.claude/skills/documentation/api-documenter \
      ~/.claude/skills/documentation/company-api-documenter
undefined

Edit to add:

沙箱兼容性

- Company API standards

—

- Custom response formats

—

- Internal schemas

—
undefined
无沙箱环境下可用： ✅ 是 沙箱环境下可用： ✅ 是
  • 文件系统： 可写入OpenAPI文件
  • 网络： 无需网络
  • 配置： 无需额外配置

Sandboxing Compatibility

最佳实践

Works without sandboxing: ✅ Yes Works with sandboxing: ✅ Yes
  • Filesystem: Writes OpenAPI files
  • Network: None required
  • Configuration: None required
  1. 保持注释更新 - 文档与代码同步
  2. 使用类型提示 - TypeScript、Python类型定义有助于生成更准确的文档
  3. 包含示例 - 使用真实场景的请求/响应示例
  4. 文档错误信息 - 记录所有可能的错误响应
  5. API版本化 - 在端点中包含版本信息

Best Practices

相关工具

  1. Keep comments updated - Documentation follows code
  2. Use type hints - TypeScript, Python types help
  3. Include examples - Real-world request/response
  4. Document errors - All possible error responses
  5. Version your API - Include version in endpoints
  • @docs-writer子Agent：生成用户指南和教程
  • readme-updater skill：保持README文档更新
  • /docs-gen命令：生成完整的文档

Related Tools

—
  • @docs-writer sub-agent: User guides and tutorials
  • readme-updater skill: Keep README current
  • /docs-gen command: Full documentation generation
—