OpenAPI Spec Primer

Why OpenAPI

OpenAPI (formerly Swagger) is the lingua franca of REST APIs. A single YAML or JSON file drives interactive docs, client SDK generation, mock servers, and contract testing. Teams that adopt spec-first development catch breaking changes before they reach production.

Minimal Structure

openapi: "3.1.0"
info:
  title: Nimbus API
  version: "1.0.0"
paths:
  /license/activate:
    post:
      summary: Activate a license
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                hwid:
                  type: string
      responses:
        "200":
          description: Activation token

Three required root keys: openapi, info, and paths. Everything else layers on top.

Schema Reuse

Define shared models under components/schemas and reference them with $ref. This keeps your spec DRY and ensures every endpoint speaks the same dialect.

Tooling

• Redocly — lint, bundle, and preview specs locally.
• openapi-generator — emit TypeScript, Python, Go clients from a single command.
• Prism — mock server that validates requests against your spec in real time.

Next Steps

Start with a single endpoint. Validate it with Redocly. Generate a client. Once the loop feels natural, expand to cover every route in your API surface. Your future self — and every integrator — will thank you.