TL;DR
OpenAPI (formerly Swagger) is a standard for describing REST APIs in YAML/JSON. From one spec you can generate documentation (Swagger UI, Redoc), clients in different languages and server stubs. Keep the spec in the repo next to code and treat it as the contract between frontend and backend. Plan API versioning (e.g. /v1/, /v2/) from the start.
Who this is for
- Backend and frontend developers working through an API
- API architects and product owners
- Teams exposing APIs to external clients
Keyword (SEO)
openapi swagger, api documentation, api versioning, rest api specification
Why OpenAPI?
- Single spec – describes endpoints, request/response, types, examples
- Readable docs – Swagger UI, Redoc – for team and partners
- Code generation – clients (TypeScript, Python, etc.) and server stubs from one file
- Testing – tools (Postman, Dredd) can validate API against the spec
- Contract – frontend and backend agree on spec; changes = explicit version
Basic spec structure
openapi: 3.0.3
info:
title: My API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
email:
type: string
format: email
name:
type: string
Docs from the spec
- Swagger UI – interactive docs, can run requests (e.g. with auth)
- Redoc – readable, “book-style” layout
- Both can be generated from the same OpenAPI file (e.g. in CI or at server start)
Code generation
- openapi-generator (OpenAPI Generator) – clients: TypeScript, Python, Java, Go… and server stubs
- Orval (for TypeScript/React) – generates types and API call functions from OpenAPI
- Frontend stays in sync with types and endpoints after refreshing the spec
API versioning
- URL – e.g.
/v1/users,/v2/users– clear, caching and proxies are simple - Header – e.g.
Accept: application/vnd.api.v1+json– cleaner URL, less common - Policy – with URL versioning define when v1 is deprecated and when it’s retired; document and use headers (e.g.
Deprecation,Sunset)
Recommendation: version in URL (/v1/) for public API; internally you can be more flexible.
Best practices
- Spec as source of truth – keep in repo, update when API changes; CI can validate server against spec (e.g. contract tests)
- Semantic versioning – e.g. 1.0.0 → 1.1.0 for new field (backward compatible), 2.0.0 for breaking change
- Descriptions and examples –
description,examplein schemas help API consumers securitysection – describe required headers (Bearer, API key); Swagger UI can set them for tests
Checklist
- OpenAPI file in repo (YAML or JSON)
- Documentation (Swagger UI / Redoc) available to team and clients
- Client (or types) generation in build
- Versioning rules (v1, v2) and deprecation
- Contract tests (optional) – server responses match spec
FAQ
Does OpenAPI replace “manual” documentation?
It doesn’t have to. OpenAPI describes the contract (endpoints, schemas). You can add separate docs (e.g. “How to get a token”, business scenarios) in a wiki or in the spec’s descriptions.
What about GraphQL?
OpenAPI is for REST. For GraphQL use the GraphQL schema and tools like GraphQL Playground, Apollo Studio. The idea of “one spec = docs + generation” is similar.
How to keep code in sync with the spec?
Option 1: generate stub from OpenAPI and extend it. Option 2: write code by hand and in CI generate spec from code (e.g. annotations in Java, decorators in Python) and compare to the “golden” OpenAPI file. Option 3: contract tests – validate request/response from tests against the spec.