OpenAPI — API Contracts in YAML

API documentation, validation, and SDK generation, from one YAML file

OpenAPI 3.x (formerly Swagger) describes HTTP APIs in a YAML or JSON document. Tools render docs (Redoc, Swagger UI), validate requests/responses (Stoplight, Spectral), and generate SDKs in dozens of languages — all from the same source file.

Top-level shape

openapi: — spec version (3.1.0 currently).
info: — title, version, description.
paths: — endpoints. Each path → method (get/post/etc.) → parameters/requestBody/responses.
components: — reusable schemas, parameters, responses, security schemes.

Why YAML over JSON

OpenAPI specs are often hundreds of lines with deeply nested schemas. Comments, anchors, and folded strings make YAML readable where the equivalent JSON would be a wall. The spec accepts both; teams choose YAML by majority.

Schema-first vs code-first: two valid workflows. Schema-first writes the OpenAPI YAML by hand, then generates server stubs and clients. Code-first writes the server (FastAPI, NestJS, ASP.NET) and emits the OpenAPI from decorators. Schema-first gives a stricter contract; code-first gives a tighter feedback loop. Pick based on team size — small team → code-first, multi-team API → schema-first.

Code

A small but complete OpenAPI doc·yaml

openapi: 3.1.0
info:
  title: Pippa API
  version: 1.0.0
  description: Toy API for the markup quest.

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:    { type: integer }
        name:  { type: string  }
        email: { type: string, format: email }
      required: [id, name, email]

Render docs, validate, generate clients·bash

# Live preview docs (Redocly / Stoplight Studio)
npx @redocly/cli preview-docs openapi.yaml

# Lint with Spectral (style + best practices)
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

# Generate a TypeScript client
npx openapi-typescript openapi.yaml -o api-types.ts

# Generate a Python client (openapi-generator)
openapi-generator-cli generate -i openapi.yaml -g python-pydantic-v1 -o ./gen

Reusable schema (component) referenced from multiple paths·yaml

components:
  schemas:
    Error:
      type: object
      properties:
        code:    { type: integer }
        message: { type: string  }
      required: [code, message]

paths:
  /a:
    get:
      responses:
        '500':
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /b:
    get:
      responses:
        '500':
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

OpenAPI — API Contracts in YAML

API documentation, validation, and SDK generation, from one YAML file

Top-level shape

Why YAML over JSON

Code

External links

Exercise

Progress

Comments 0