OpenAPI

OpenAPI (formerly Swagger) is a standard, machine-readable way to describe a REST API: its paths, operations, parameters, request/response schemas, and status codes. A single document drives docs, client generation, mock servers, and tests.

A minimal description

Here is one endpoint described in OpenAPI 3.1 (YAML):

openapi: 3.1.0
info:
  title: Blog API
  version: 1.0.0
paths:
  /articles/{id}:
    get:
      summary: Get an article by id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: Not found
components:
  schemas:
    Article:
      type: object
      required: [id, title]
      properties:
        id: { type: string }
        title: { type: string }
        body: { type: string }

Each operation lists its parameters and every response it can return, each tied to a schema. The components/schemas section defines reusable shapes referenced with $ref.

Spec-first vs code-first

Spec-first — write the OpenAPI document, then implement against it. The contract is agreed before code exists; great for teams and external consumers.
Code-first — annotate your handlers/schemas and generate the spec from them. Less drift between code and spec, since one produces the other.

Either way, tooling turns the spec into value: Swagger UI / Redoc render interactive docs, generators produce typed clients, and validators check requests against it.

Advantages (OpenAPI)	Trade-offs
Docs generated from the schema — never drift from the code	Setting up an OpenAPI spec takes upfront discipline
Automatic SDK generation for many languages	The spec file itself gets verbose — large YAML/JSON
Validation middleware from the schema — requests/responses always match it	Choosing code-first vs. spec-first is a real decision
Contract testing between producer and consumer	The spec goes stale if developers don’t update it with the code

Common mistakes

OpenAPI spec that drifts from the implementation Symptom:

The spec is written first and implementation follows — then the implementation changes without updating the spec
Developers generate a client from a stale spec — bugs show up at integration time
Generate the spec from the code (code-first), or enforce spec validation in CI

No examples in the spec Symptom:

The spec has type definitions but no example request/response
Developers don’t know what value a field expects — they have to guess
Add an example or examples field to every request/response body in the spec

💡 Real-world examples

Stripe API:

A comprehensive OpenAPI spec — every endpoint has a schema, an example, and error responses

Used to generate SDKs for 7+ languages: Python, Ruby, Node.js, Go, Java, PHP, .NET

GitHub API:

Publishes its OpenAPI description publicly — the community builds SDKs and tools on top of it

Every language’s Octokit client is generated from that same spec

Sources: Stripe API libraries, GitHub REST API description