Generate and Validate OpenAPI Specifications

Covers OpenAPI 3.1 spec structure and three design approaches - design-first, writing the spec before code, best for new APIs and contracts; code-first, generating the spec from existing code; and hybrid, annotating code to generate the spec, best for evolving APIs. Ships four templates: a complete design-first API specification, code-first generation from Python and FastAPI (which produces the OpenAPI spec automatically from typed endpoint, enum, and Pydantic model definitions and can export it to a file), code-first generation from TypeScript and Express using tsoa, and validation and linting - installing Spectral and Redocly CLIs, a .spectral.yaml ruleset enforcing required operationIds and descriptions, security definitions on every operation, defined success responses, snake_case path parameters, and camelCase schema properties via custom rules, plus a redocly.yaml config enforcing valid media-type examples, allowed request and response MIME types, and generating curl, Python, and JavaScript code samples in the rendered docs, run via spectral lint and redocly lint, bundle, and preview-docs. Covers SDK generation with OpenAPI Generator, producing a TypeScript client (typescript-fetch generator with ES6 support and an npm package name), a Python client, and a Go client, each from the same spec file via the same CLI with a different -g target.

Use it when writing or generating an OpenAPI specification, choosing between design-first and code-first approaches, validating or linting an API spec, or generating client SDKs from a spec. Skip it for anything unrelated to OpenAPI spec generation or outside this scope.

Input is an API's endpoints and models, or an existing spec to validate; output is a complete OpenAPI 3.1 YAML spec, either hand-written or code-generated, a linting report from Spectral or Redocly with the specific rule violations, or a generated client SDK in TypeScript, Python, or Go.

FastAPI for Python code-first generation, tsoa for TypeScript and Express code-first generation, Spectral and Redocly CLIs for linting and documentation preview, and OpenAPI Generator for multi-language SDK generation from a finished spec.

API teams producing or maintaining an OpenAPI specification who need concrete design-first and code-first templates, a working lint ruleset, and SDK-generation commands rather than the bare OpenAPI schema reference. Especially useful for teams distributing client libraries, since generating TypeScript, Python, and Go clients from one spec keeps every language binding in sync with the API instead of hand-maintaining three separate clients.