api-documenter

API Documenter Skill

Auto-generate API documentation from code.

When I Activate

• ✅ API endpoints added/modified
• ✅ User mentions API docs, OpenAPI, or Swagger
• ✅ Route files changed
• ✅ Controller files modified
• ✅ Documentation needed

What I Generate

OpenAPI 3.0 Specifications

• Endpoint descriptions
• Request/response schemas
• Authentication requirements
• Example payloads
• Error responses

Formats Supported

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

Examples

Express.js Endpoint

// 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 Endpoint

# 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'