API Documentation (OpenAPI/Swagger)

You are a developer experience architect responsible for creating world-class API documentation that accelerates consumer integration. Design a complete API documentation strategy for the following platform.

Platform Context:
API Style: [REST/GRAPHQL/GRPC/MIXED]
API Consumer Audience: [INTERNAL TEAMS/THIRD-PARTY DEVELOPERS/ENTERPRISE PARTNERS/PUBLIC]
Number of Endpoints: [TENS/HUNDREDS/THOUSANDS]
Documentation Maturity: [NONE/BASIC/MODERATE/NEEDS OVERHAUL]
Specification Standard: [OPENAPI 3.1/OPENAPI 3.0/ASYNCAPI/GRAPHQL SDL]
Documentation Hosting: [SELF-HOSTED/CLOUD PLATFORM/DEVELOPER PORTAL]

Section 1 - OpenAPI Specification Design:
Define the OpenAPI document structure including info, servers, paths, components, and security schemes sections with best practices for each. Design the component reuse strategy using shared schemas, parameters, request bodies, and response definitions in the components section. Specify the schema design patterns including discriminator for polymorphic types, oneOf and anyOf for flexible inputs, and allOf for schema composition. Create the naming conventions for operation IDs, schema names, and tag groupings that produce clean generated code. Define the specification authoring workflow including design-first versus code-first approaches with tradeoffs. Establish the specification linting rules that enforce consistency including required descriptions, example values, and error response documentation.

Section 2 - Interactive Documentation and Examples:
Design the interactive documentation experience using tools like Swagger UI, Redoc, or Stoplight Elements with customization for branding and navigation. Create the example strategy including request examples, response examples for success and error cases, and full workflow examples that chain multiple API calls. Specify the try-it-out configuration including sandbox environment setup, authentication for interactive testing, and sample data provisioning. Design the code sample generation for multiple languages including curl, JavaScript, Python, Ruby, Go, and Java with framework-specific examples. Create the use-case-driven tutorial structure that guides developers through common integration scenarios beyond individual endpoint documentation. Define the changelog and version comparison interface that helps existing consumers understand what changed between API versions.

Section 3 - SDK and Code Generation Strategy:
Define the code generation pipeline that produces typed client libraries from the OpenAPI specification for target languages. Specify the generator customization including package naming, authentication helper generation, error type mapping, and pagination helper creation. Design the SDK testing strategy that validates generated clients against the actual API using contract tests. Create the SDK distribution plan including package registry publication, versioning aligned with API versions, and installation documentation. Define the SDK documentation including getting started guides, authentication setup, and common operation examples for each target language. Specify the custom client extension points that allow generated SDK users to add interceptors, custom serialization, and retry logic.

Section 4 - Developer Portal and Onboarding:
Design the developer portal architecture including landing page, getting started guide, API reference, tutorials, changelog, and status page. Define the developer registration and API key provisioning flow including self-service signup, sandbox environment access, and production key approval process. Create the onboarding experience that takes a developer from registration to first successful API call in under five minutes. Specify the search and navigation design that helps developers find the right endpoint or concept quickly across large API surface areas. Design the community features including discussion forums, feature request tracking, and known issue documentation. Create the developer analytics dashboard that tracks documentation page views, try-it-out usage, and common search queries to identify gaps.

Section 5 - Specification Governance and CI Integration:
Define the specification-first development workflow where the OpenAPI document is the source of truth that drives implementation. Create the CI pipeline integration that validates the specification against linting rules, checks for breaking changes against the previous version, and generates documentation and SDKs automatically. Specify the specification review process including who approves changes, what automated checks must pass, and how the specification syncs with implementation. Design the mock server strategy that generates realistic API responses from the specification for frontend development before the backend is complete. Define the contract testing approach that validates the actual API implementation matches the specification. Create the specification ownership model for large organizations where multiple teams contribute endpoints to a unified API.

Section 6 - Maintenance, Analytics, and Evolution:
Define the documentation quality metrics including completeness coverage for descriptions, examples, and error documentation across all endpoints. Create the documentation freshness monitoring that detects when the specification diverges from the actual API behavior. Design the developer feedback collection integrated into the documentation including inline ratings, improvement suggestions, and confusion reporting. Specify the documentation update workflow when API changes are made including who is responsible and the SLA for documentation currency. Create the regular documentation audit process that reviews analytics, developer feedback, and support tickets to identify improvement opportunities. Document the documentation migration plan for major specification version upgrades or documentation platform changes.