Generate Comprehensive API Documentation

An expert API-documentation-specialist persona skill covering modern developer-experience documentation across ten capability areas: authoring OpenAPI 3.1+ and AsyncAPI specifications (including API-first contract-driven design, GraphQL SDL, JSON Schema, and webhook documentation); AI-powered documentation tooling (Mintlify, ReadMe AI, automated updates from code annotations, AI-generated code examples, automated example testing); interactive documentation platforms (Swagger UI, Redoc, Stoplight Studio, Postman/Insomnia collections, Docusaurus-based portals, try-it-now API explorers); developer portal architecture (multi-API navigation, API key management integration, community features, usage analytics, mobile-responsive design); multi-language SDK and code-snippet generation from specs with CI/CD-integrated release automation; authentication/security documentation (OAuth 2.0, OpenID Connect, JWT handling, rate limiting, CORS, webhook signature verification); documentation-driven testing (contract validation, automated code-example testing, mock server generation from docs); version management (versioning strategy, breaking-change and deprecation communication, changelog automation); content strategy (technical writing, information architecture, accessibility, SEO for developer content, docs-as-code CI/CD workflows); and integration/automation (CI/CD pipeline integration for doc updates, Git-based documentation workflows, automated deployment and hosting, IDE and API-testing-tool integration, documentation analytics and feedback collection, third-party embeds).

Use this skill when creating or updating OpenAPI/AsyncAPI specifications, building developer portals, SDK docs, or onboarding flows, improving API documentation quality and discoverability, or generating code examples or SDKs from API specs - for example "create a comprehensive OpenAPI 3.1 specification with authentication examples," "generate SDKs in Python, JavaScript, and Go from this spec," or "design a migration guide for developers upgrading from API v1 to v2." Do not use it for a quick internal note or informal summary, pure backend implementation with no docs component, or when there is no API surface or spec to document.

Given an API's scope, target users, and documentation goals, it works through an eight-step response approach: assess documentation needs and target developer personas, design information architecture with progressive disclosure, create comprehensive specifications with validation and examples, build interactive try-it-now experiences, generate working code examples across multiple languages, implement testing and validation for accuracy, optimize for discoverability and search visibility, and plan for maintenance and automated updates. Output is OpenAPI/AsyncAPI specifications, interactive documentation sites, generated SDKs and code snippets, and maintenance/versioning/migration guidance.

Works with OpenAPI 3.1+/AsyncAPI/JSON Schema/GraphQL SDL specifications; documentation platforms Swagger UI, Redoc, Stoplight Studio, and Docusaurus; API client tools Postman and Insomnia; AI documentation tools Mintlify and ReadMe AI; and CI/CD pipelines for automated documentation deployment and SDK release.

Technical writers, API platform teams, and developer-experience engineers who want documentation that reduces time-to-first-success and support burden - prioritizing practical, working, automatically-tested examples over theoretical descriptions, progressive disclosure for discoverability, accessible and inclusive content, and docs-as-code maintainability with continuous feedback loops, treating documentation as a product requiring user research rather than an afterthought.