openapi-spec-generation

FastAPI automatically generates an OpenAPI spec from your Pydantic models and route decorators. Define models with Field validation, set response_model and status_code on endpoints, then export the spec as JSON by calling app.openapi().

Start with the design-first template defining info, servers, paths, and components sections. Reuse schemas, parameters, and responses through $ref references, and define securitySchemes like bearerAuth or apiKey under components.

Design-first means writing the spec before implementing code, which suits new APIs and contract agreements. Code-first generates the spec from annotated code, which fits existing APIs built with frameworks like FastAPI or tsoa.

Install @stoplight/spectral-cli and create a .spectral.yaml ruleset extending spectral:oas. Add rules for operationId presence, descriptions, and naming conventions, then run spectral lint on your spec file.

Yes, use openapi-generator-cli with your spec file to generate clients for TypeScript (typescript-fetch), Python, or Go. Pass generator-specific options through the additional-properties flag such as package names.

Avoid code-first when multiple teams must agree on a contract before implementation begins, or when the API consumers are external partners. In those cases, design-first specs provide a stable agreement independent of implementation details.