api-documentation-skill_skill

Overview

This skill generates comprehensive, professional API documentation that follows industry best practices. It produces clear overviews, authentication guides, endpoint references, examples, error lists, and changelogs to help developers onboard quickly. The output is suitable for REST, GraphQL, and OpenAPI-driven projects.

How this skill works

The skill inspects API surface details—endpoints, parameters, request/response schemas, auth methods, rate limits, and version history—and formats them into a consistent documentation structure. It produces working request/response examples, code snippets in multiple languages, error code tables, OpenAPI snippets when appropriate, and suggestions for interactive docs and tooling.

When to use it

• Creating initial API reference for a new service
• Converting API specs into developer-friendly docs
• Generating README or onboarding guides for API consumers
• Producing OpenAPI/Swagger or Postman collections from endpoints
• Documenting version changes and release notes

Best practices

• Start with a concise overview describing purpose and intended audience
• Include concrete authentication examples (Bearer, API key, OAuth) and required headers
• Provide real, working request/response examples with realistic data
• Document all error codes, causes, and resolutions with sample responses
• Offer OpenAPI/Swagger output and Postman collections for interactive exploration

Example use cases

• Generate a full reference for GET/POST/PUT/DELETE endpoints with path and query parameter details
• Create a changelog and versioning section for a v2.0 release that lists breaking changes
• Produce code samples in Java, Python, and JavaScript for common API calls
• Create a rate limit section with header names, limits per tier, and example 429 payload
• Convert internal API notes into a public developer guide with edge-case behavior and validation rules