OpenAPI Specification

There is a standard for expressing the shape of an HTTP API as a machine-readable document. That is the OpenAPI Specification (OAS). Once it is written well, doc pages, client SDKs, mocks, and contract tests all flow from the same source.

1. About OpenAPI

Event	Time
Swagger spec first published (Wordnik · Tony Tam et al.)	2010–2011
2.0 (Swagger 2.0)	2014
OpenAPI Initiative founded (under Linux Foundation) · spec donated	2015–2016
OpenAPI 3.0	2017
OpenAPI 3.1 (aligned with JSON Schema 2020-12)	2021

"Swagger" remains the name of SmartBear's tools today (e.g. Swagger UI, Swagger Editor), while the spec itself moved under the OpenAPI name.

OpenAPI documents are written in YAML or JSON and express:

• Server URLs and authentication methods.
• Paths (paths) and methods, with parameters, request body, and response schemas.
• Reusable components (components.schemas · parameters · responses · securitySchemes).
• Tags, examples, and external doc links.

From 3.1, alignment with JSON Schema 2020-12 improved compatibility with validation tools.

2. Auto-generation from code

Several frameworks analyze handler signatures and types to auto-generate OpenAPI documents.

Framework / tool	Notes
FastAPI	Auto-generates from handlers and Pydantic models. Exposes /openapi.json · /docs · /redoc by default.
springdoc-openapi	Generates from annotations and DTOs on top of Spring Boot.
NestJS Swagger	Decorator + module registration.
Hono OpenAPI	Generates from zod schemas via helpers like @hono/zod-openapi.
drf-spectacular	OpenAPI generator for Django REST framework.
Goa · Huma	Code → spec automation in the Go camp.

Auto-generation may fail to capture dynamic responses far from the handler, so manual supplementation is sometimes needed.

3. Code generation from spec

The reverse — spec → code — is also possible.

• openapi-generator (a fork of swagger-codegen, 2018) — multi-language client and server stub generation.
• oazapfts (TS) — spec → TS client.
• kubb · orval (TS) — spec → React Query/Vue Query hook generation.
• Connect / gRPC-gateway — another flavor of spec-first flow (Protobuf based).

4. Viewers and editors

Tool	Notes
Swagger UI	The longest-standing standard viewer. SmartBear.
Redoc	Redocly's static doc generator. Single-page layout.
Scalar	A relatively recent (around 2023) viewer. Clean UI with a try-it console.
Stoplight Elements	Embeddable doc components.

A viewer can plug in anywhere as long as a spec exists. The /docs FastAPI exposes by default is Swagger UI; /redoc is Redoc.

5. Other spec candidates

• JSON Schema alone — focused on data validation. HTTP semantics must be added on top.
• gRPC + Protobuf — RPC model + binary serialization. gRPC-Web and Connect bridge it for browsers.
• GraphQL — the schema is the query language. Client-driven response shape.
• AsyncAPI — a spec for message-based systems (Kafka · MQTT · AMQP · WebSocket). Sometimes called the messaging counterpart of OpenAPI.
• TypeSpec (Microsoft, 2023) — written like code and converted to OpenAPI · JSON Schema.

OpenAPI is optimized for HTTP REST, while AsyncAPI fits better in messaging, events, and real-time settings.

6. Spec-first vs code-first

• Code-first — spec auto-generated from code. Quick to start, naturally synchronized with code.
• Spec-first — agree on the spec first → both server and client generate code from it. Inter-team contracts are clear.

In large-scale and multi-team collaboration, the value of spec-first often grows.

7. FastAPI auto-generation

OpenAPI is built from handlers and Pydantic models without extra work. Adding metadata:

app = FastAPI(
    title='My API',
    version='1.2.0',
    openapi_tags=[{'name': 'users', 'description': '...'}],
)

@app.get('/u/{id}', response_model=UserOut, responses={404: {'model': ErrorOut}})
def get_user(id: int): ...

8. Client SDK generation and static docs

The lightest flow that only extracts types:

npx openapi-typescript https://api.example.com/openapi.json -o api.d.ts

For tools that build call functions too, options like oazapfts and kubb exist.

A single HTML build via Redoc CLI:

npx @redocly/cli build-docs openapi.yaml -o docs.html

9. Common pitfalls

Version confusion — 3.0 and 3.1 differ in JSON Schema compatibility (e.g. nullable representation). Verify which version the tool supports.

Meaning of oneOf/anyOf/allOf — auto-generators may not follow them precisely, leading to awkward client types. Use explicit discriminators (the discriminator keyword) where possible.

Missing auth schema — without securitySchemes and per-route security, generated client SDKs cannot build auth headers.

Conflict between auto-generated spec and manual edits — every regeneration overwrites. Backstop with code annotations or post-processing scripts.

Exposing sensitive endpoints — decide whether to expose /openapi.json itself in production. If internal-only, block at the gateway.

Closing thoughts

Once OpenAPI is written well, docs, SDKs, and mocking all follow. In environments like FastAPI where the spec is auto-generated from code, the cost of writing a spec is nearly zero. For externally exposed APIs, an OpenAPI spec is recommended.

Next

• rest-api-intro
• websocket-sse

See OpenAPI Specification · OpenAPI Initiative · Swagger toolset · Redoc · Redocly CLI · openapi-generator · AsyncAPI · JSON Schema.