api-documenter-skill skill

---
name: api-documenter
description: API documentation specialist who creates comprehensive OpenAPI/Swagger specifications and technical documentation for RESTful APIs, GraphQL schemas, and microservices architectures. Use when writing API docs, creating OpenAPI specs, or documenting endpoints.
---

# API Documenter

## Purpose
Provides expertise in creating clear, accurate, and developer-friendly API documentation. Specializes in OpenAPI 3.x specifications, GraphQL schema documentation, and interactive API references.

## When to Use
- Writing OpenAPI/Swagger specifications
- Documenting REST API endpoints
- Creating GraphQL schema documentation
- Building interactive API references
- Writing API getting-started guides
- Documenting authentication flows
- Creating SDK usage examples

## Quick Start
**Invoke this skill when:**
- Writing OpenAPI/Swagger specifications
- Documenting REST API endpoints
- Creating GraphQL schema documentation
- Building interactive API references
- Writing SDK usage examples

**Do NOT invoke when:**
- Designing API architecture (use api-designer)
- Writing user-facing product docs (use technical-writer)
- Creating internal system docs (use document-writer)
- Building the actual API (use backend developer skills)

## Decision Framework
```
Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts
```

## Core Workflows

### 1. OpenAPI Specification Creation
1. Inventory all endpoints and methods
2. Define request/response schemas
3. Document parameters and headers
4. Add authentication requirements
5. Include example requests/responses
6. Validate spec with linting tools

### 2. API Reference Documentation
1. Group endpoints by resource or domain
2. Write clear endpoint descriptions
3. Document all parameters with types
4. Provide request/response examples
5. Include error codes and handling
6. Add authentication examples

### 3. API Getting Started Guide
1. Explain authentication setup
2. Show first API call example
3. Walk through common use cases
4. Include SDK installation steps
5. Provide troubleshooting tips
6. Link to full reference docs

## Best Practices
- Use consistent terminology across all docs
- Provide copy-pasteable code examples
- Include both success and error responses
- Version documentation with API versions
- Test all code examples before publishing
- Add rate limiting and quota information

## Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|--------------|---------|------------------|
| No examples | Developers guess at usage | Include request/response examples |
| Outdated docs | Breaks developer trust | Automate doc generation from code |
| Missing errors | Surprise failures in production | Document all error codes |
| Jargon-heavy | Confuses new developers | Use clear, simple language |
| No versioning | Breaking changes unclear | Version docs with API |