api-documentation-generator_skill

Overview

This skill generates comprehensive, developer-friendly API documentation including OpenAPI/Swagger specs, endpoint descriptions, request/response examples, and integration guides. It produces ready-to-use artifacts like an OpenAPI 3.0 YAML, a README-style quick start, authentication and error handling sections, and sample SDK instructions. Built with TypeScript conventions in mind, it targets consistency and clarity for developer portals and repos.

How this skill works

The skill analyzes API surface details (endpoints, parameters, schemas, auth, error responses) and emits a complete OpenAPI 3.0 specification plus human-readable documentation. It creates example requests and responses, security definitions (e.g., Bearer JWT), pagination and query parameter descriptions, and integration snippets (curl, SDK install). The output is structured for direct publication or further editing and includes a checklist to verify completeness.

When to use it

• Document a new or existing REST API before public release
• Generate an OpenAPI/Swagger spec for client generation or testing
• Create a README or developer guide with quick start and auth examples
• Produce request/response examples and error documentation for support teams
• Prepare API docs for SDK generation or CI publishing

Best practices

• Include all endpoints, path and query parameters, and required request bodies
• Provide concrete request and response examples for common flows and errors
• Document authentication flows and required headers clearly (e.g., Authorization: Bearer <token>)
• Version the API and include server environments (production, staging, local)
• Keep schemas DRY with reusable components and reference them from paths
• Add rate limit, error codes, and changelog information for operational clarity

Example use cases

• Generate OpenAPI 3.0 YAML to drive client SDK and contract tests
• Create a README quick start with curl examples for onboarding new integrators
• Produce endpoint-level docs including pagination, filters, and role-based access notes
• Document authentication and common error payloads for frontend and mobile teams
• Build a publishable developer guide that includes installation and support links