API 文档生成器

Overview

This skill analyzes your API endpoints and generates professional documentation including examples, schemas, and error handling details.

SKILL.md Template

---
name: api-docs
description: Generate comprehensive API documentation from code. Use when documenting endpoints, creating OpenAPI specs, or updating API references.
---

When documenting APIs, generate:

## 1. Endpoint Overview
- HTTP method and path
- Brief description
- Authentication requirements
- Rate limiting info

## 2. Request Documentation
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |

### Path Parameters
Document each URL parameter with type and constraints.

### Query Parameters
Document filtering, pagination, sorting options.

### Request Body
```json
{
  "field": "value",
  "nested": {
    "example": "with types noted"
  }
}

3. Response Documentation

Success Response (200)

{
  "data": {},
  "meta": {
    "pagination": {}
  }
}

Error Responses

4. Code Examples

Provide examples in:

• cURL
• JavaScript (fetch)
• Python (requests)

Output Format

Use OpenAPI 3.0 compatible structure when possible.

## Example Output

```markdown
# Create User

Creates a new user account.

`POST /api/v1/users`

## Authentication
Requires admin API key in header.

## Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Full name (2-100 chars) |
| role | enum | No | "user" or "admin" (default: "user") |

### Example
```json
{
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "user"
}

Responses

201 Created

{
  "id": "usr_123abc",
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "user",
  "createdAt": "2024-01-15T10:30:00Z"
}

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}

Code Examples

cURL

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "name": "Jane Doe"}'

JavaScript

const response = await fetch('https://api.example.com/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    name: 'Jane Doe'
  })
});

## Usage

/api-docs src/routes/users.ts

## Tips

- Keep examples realistic but safe (no real credentials)
- Include rate limit information
- Document deprecation warnings
- Add links to related endpoints