APIs & Authentication
What is OpenAPI?
A specification format for describing REST APIs in a machine-readable schema, used to generate documentation, client SDKs, and server stubs.
Also known as: Swagger Specification
OpenAPI (formerly Swagger Specification) is a YAML or JSON document that describes every endpoint of an API: the path, method, parameters, request body schema, response schemas, error codes, and authentication. A single openapi.yaml file is the contract between server and client, and it can drive generated clients in dozens of languages.
The ecosystem around OpenAPI is the real value. Swagger UI renders the spec as interactive docs. Stoplight, Redoc, and Bump.sh do the same with different aesthetics. openapi-generator and orval produce typed clients in TypeScript, Python, Go, Rust, and more. Mock servers (Prism, Mockoon) replay the spec without you writing any backend.
OpenAPI 3.1 is the current revision and aligns with JSON Schema 2020-12, which means your spec's schemas can be used directly by validation libraries. The biggest practical limitation is that the spec describes shape but not behavior: you still need prose and examples for things like rate-limit semantics, idempotency keys, and retry strategy.
In the wild
- →Stripe publishing an openapi.json that hundreds of community SDKs are generated from
- →A team running orval over the spec on every backend deploy to keep the TypeScript client in sync
- →A QA team using Prism as a mock server so the frontend can develop against an unbuilt endpoint
How Brand.dev uses openapi
Endpoints in the Brand.dev API where this concept comes up directly.
FAQ
OpenAPI vs Swagger?
OpenAPI is the open spec; Swagger is the brand and toolset (Swagger UI, SwaggerHub) that originated it. The spec was renamed in 2016 when SmartBear donated it to the OpenAPI Initiative.
OpenAPI vs GraphQL schema?
OpenAPI describes a REST surface; a GraphQL SDL describes a graph. Different paradigms, both machine-readable. You would not use OpenAPI to describe a GraphQL endpoint.
Should I write the spec by hand or generate it from code?
Generate from code if you have a typed framework (FastAPI, NestJS with decorators); hand-write if your design needs to lead the implementation. Either way, the spec belongs in version control.
Related terms
A toolset (and historical predecessor of OpenAPI) for designing, documenting, and consuming REST APIs through a machine-readable schema.
An API that follows REST conventions, using HTTP methods on resource URLs to model create/read/update/delete operations.
An Application Programming Interface, a contract that lets one program request actions or data from another in a stable, documented way.
JavaScript Object Notation, a lightweight text format for representing structured data, supported natively by every modern language.
A query language for APIs that lets the client specify exactly the fields it wants from a typed graph of data, returned in one round trip.