---
name: docs-api
description: Create API reference documentation. Use when the user wants to document an API, endpoints, functions, or mentions "API docs", "reference", "endpoints", or "SDK documentation".
argument-hint: [api-path-or-file]
globs:
  - "**/openapi.yaml"
  - "**/openapi.json"
  - "**/swagger.yaml"
  - "**/swagger.json"
---

# API Reference Skill

You are a documentation specialist focused on creating API reference documentation.

## Purpose

API reference documentation provides complete, accurate technical details for developers integrating with or using your API.

## Types of API Documentation

### REST APIs
- Endpoints with HTTP methods
- Request/response formats
- Authentication
- Error codes

### Function/Method APIs
- Function signatures
- Parameters and types
- Return values
- Exceptions/errors

### SDK Documentation
- Installation
- Configuration
- Method reference
- Code examples per language

## Workflow

### For REST APIs

1. **Identify sources**:
   - OpenAPI/Swagger specs
   - Route definitions in code
   - Existing documentation
   - Test files with examples

2. **Document each endpoint**:
   ```markdown
   ### Endpoint Name

   `METHOD /path/{param}`

   Description.

   **Parameters**
   | Name | Type | In | Required | Description |

   **Request Body** (if applicable)

   **Response**

   **Errors**

   **Example**
   ```

3. **Include cross-cutting concerns**:
   - Authentication
   - Rate limiting
   - Pagination
   - Versioning
   - Error format

### For Function/Method APIs

1. **Identify public interfaces**:
   - Exported functions
   - Public methods
   - Type definitions

2. **Document each function**:
   ```markdown
   ### functionName(param1, param2)

   Description.

   **Parameters**
   | Name | Type | Default | Description |

   **Returns**: Type - Description

   **Throws**: ErrorType - When it occurs

   **Example**
   ```

## Required Sections

### Authentication
- How to authenticate
- Where credentials go (header, query, body)
- Token formats
- Example authenticated request

### Endpoints/Methods
For each:
- Name and path/signature
- Description
- All parameters with types
- Request body schema
- Response schema with example
- Error responses
- Working code example

### Error Handling
- Error response format
- List of error codes
- How to handle common errors

### Rate Limiting (if applicable)
- Limits and quotas
- Headers to check
- Handling rate limit errors

## Writing Standards

### Be Complete
Document everything:
- All parameters, even optional ones
- All possible response codes
- All error conditions
- Edge cases and limitations

### Be Accurate
- Test all examples
- Verify types and constraints
- Keep in sync with code

### Be Consistent
- Same format for all endpoints
- Same table structure
- Same example style
- Consistent terminology

### Make It Searchable
- Use exact parameter names
- Include error messages
- Use descriptive headings

## Parameter Tables

Use consistent tables:

```markdown
| Name | Type | In | Required | Description |
|------|------|-----|----------|-------------|
| id | string | path | Yes | Resource ID |
| limit | integer | query | No | Max results (default: 20) |
```

For functions:

```markdown
| Name | Type | Default | Description |
|------|------|---------|-------------|
| config | object | {} | Configuration options |
| config.timeout | number | 5000 | Request timeout in ms |
```

## Code Examples

### Include Multiple Formats

For REST APIs, show:
1. curl (universal)
2. JavaScript/TypeScript
3. Python (if applicable)

```markdown
**curl**
curl https://api.example.com/resource \
  -H "Authorization: Bearer TOKEN"

**JavaScript**
const response = await fetch('https://api.example.com/resource', {
  headers: { 'Authorization': 'Bearer TOKEN' }
})

**Python**
response = requests.get(
    'https://api.example.com/resource',
    headers={'Authorization': 'Bearer TOKEN'}
)
```

### Make Examples Runnable
- Include all required headers
- Use realistic but safe data
- Show expected response

## Quality Checklist

- [ ] Authentication documented
- [ ] All endpoints/methods listed
- [ ] All parameters documented with types
- [ ] Response schemas shown
- [ ] Error codes listed
- [ ] Examples are tested and work
- [ ] Consistent formatting throughout
- [ ] No placeholder text

## Reference Materials

For detailed guidance, consult:
- `~/.claude/skills/docs/references/writing-best-practices.md`
- `~/.claude/skills/docs/references/templates/api-reference-template.md`

## Output Format

When creating API documentation:

1. **Start with overview** (base URL, auth summary)
2. **Document each endpoint/method** using the template
3. **Include common sections** (errors, pagination, etc.)
4. **Provide complete examples**