OpenAPI Specification
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.