Generate Comprehensive API Reference Guides

This skill provides expertise in creating comprehensive API documentation that developers love to use, specializing in clear, accurate, practical docs covering endpoint descriptions, authentication methods, request/response examples, error handling, and interactive elements. Core documentation principles include a developer-first approach (writing from the implementer's perspective), clarity over brevity (enough detail to avoid confusion), consistency (uniform patterns for similar concepts across endpoints), completeness (covering every endpoint, parameter, response, and edge case), and testability (working examples developers can copy and run).

The reference guide structure organizes documentation as: Overview (API purpose, base URL, versioning strategy), Authentication (methods, tokens, headers, examples), Endpoints (grouped by resource with full CRUD operations), Error Handling (standard error codes and responses), Rate Limiting (limits, headers, best practices), SDKs and Libraries (available client libraries), and a Changelog (version history and breaking changes). Authentication documentation provides clear examples in both curl and SDK form, plus authentication troubleshooting and token refresh procedures. The endpoint documentation format specifies, for each endpoint, its parameters (path/query, required/optional), a curl example request, and an example JSON response - covering both read (GET with includes) and write (POST with a documented request body schema) operations.

Error documentation covers every possible error response with a consistent JSON structure (error code, message, field-level details, request ID) and the standard HTTP status codes used (200, 201, 400, 401, 403, 404, 429, 500). Interactive examples are provided in multiple languages (curl, Python via requests, Node.js via fetch) so developers can copy directly into their stack. Data types and schemas define clear OpenAPI-style schemas for each resource with field descriptions, formats, and examples. Advanced capabilities documented include filtering (?filter[status]=active), pagination (page/limit/total_count parameters), sorting (?sort=-created_at,email), field selection (?fields=id,email), webhooks (event types, payload structures, retry logic), batch operations (bulk create/update/delete examples), and idempotency keys for safe retries. Best practices cover consistent parameter naming (snake_case or camelCase), realistic example data rather than placeholder text, both success and error response examples, clearly documented required/optional parameters, rate-limit header documentation, troubleshooting sections for common issues, OpenAPI/Swagger specs where possible, deprecation notices with migration paths, and testing every code example before publishing.

Use this skill when writing or improving API reference documentation that needs complete endpoint coverage, working code examples in multiple languages, and consistent error documentation. It is well suited to public or partner-facing APIs where developer experience directly affects adoption. It is not meant for internal-only scripts with no external documentation audience, or for a single quick endpoint note where full reference structure is unnecessary.

Input: the API's endpoints, authentication method, and resource schemas.

Output: a complete API reference guide with overview, authentication docs, per-endpoint documentation, error handling, rate limiting, and multi-language examples. Example endpoint documentation format:

curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "12345",
  "email": "user@example.com",
  "profile": {"first_name": "John", "last_name": "Doe"}
}

Documents REST APIs following OpenAPI/Swagger conventions, with code examples in curl, Python, and Node.js.

Developer relations and API teams writing public or partner-facing API documentation, and teams that need consistent, tested, multi-language reference docs rather than sparse endpoint notes.