api-docs-generator_skill

Overview

This skill generates complete API documentation from source code and specifications in OpenAPI/Swagger, Markdown, interactive HTML, or Postman Collection formats. It produces developer-friendly docs including request/response examples, authentication, error references, rate limit info, and client code snippets. Use it to standardize, publish, or version your API documentation quickly.

How this skill works

Provide endpoint definitions, controller or project source, or a GraphQL schema and the skill analyzes routes, parameters, models, and comments to build structured outputs. It can emit OpenAPI 3.0 YAML/JSON, Git-friendly Markdown, Swagger UI-ready HTML, or a Postman Collection with environment variables and auth presets. It also generates sample requests, responses, security schemes, and common error and pagination models.

When to use it

• Document a REST API from controllers, routers, or route annotations
• Create a machine-readable OpenAPI/Swagger spec for tooling and client generation
• Export a Postman Collection for QA or external teams
• Publish Markdown docs to GitHub/GitLab or generate static site HTML
• Document GraphQL schemas as readable reference with types and queries

Best practices

• Include clear request/response examples and realistic sample data
• Annotate authentication requirements and include sample auth flows
• Keep model schemas centralized to avoid inconsistencies across endpoints
• Version specs and include changelogs or deprecation notes for breaking changes
• Validate generated OpenAPI against a linter or schema validator before publishing

Example use cases

• Generate OpenAPI 3.0 for an Express.js project and serve via Swagger UI
• Produce Markdown reference for a public API repository README
• Export a Postman Collection for onboarding QA and external integrators
• Create client code snippets (JavaScript, Python, cURL) for SDK docs
• Document GraphQL schema fields and example queries for frontend teams