Documenting APIs with OpenAPI

OpenAPI (formerly Swagger) is a standard, machine-readable description of a REST API. One spec file can produce interactive docs, client SDKs, mock servers and request validation.

A minimal spec

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}:
    get:
      summary: Get an order
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Order not found
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id: { type: string, example: ord_42 }
        status: { type: string, enum: [pending, paid, shipped] }
        total: { type: integer, description: Amount in paise }
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
security:
  - bearerAuth: []

Spec-first or code-first?

• Code-first: generate the spec from your code. FastAPI does this automatically; Node frameworks have plugins or Zod-based generators.
• Spec-first: write the spec, review it with consumers, then implement. Good for public APIs and teams that agree on contracts up front.

What to generate from it

• Docs: Swagger UI, Redoc or Scalar.
• Typed clients: openapi-typescript for TypeScript types, or OpenAPI Generator for many languages.
• Request/response validation middleware.
• Mock servers so front-end work can start before the backend is ready.

npx openapi-typescript openapi.yaml -o src/api-types.ts

Keep it honest

A wrong spec is worse than none. Validate responses against the spec in tests, or lint it in CI (Spectral and Redocly CLI are popular), so the docs can't drift from reality.