The OpenAPI standard

In the last lesson, we talked about why hand-written docs always go stale and why generating docs from code is the way forward. But generating docs means you need a format. You cannot just dump your source code on someone and call it documentation. You need a structured, standardized way to describe your API. That is what OpenAPI is.

OpenAPI (formerly called Swagger) is a standard for describing REST APIs. An OpenAPI spec is a JSON file that lists every endpoint, every parameter, every request body, every response, and every error in your API. It looks like this:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Book Catalog API",
    "version": "2.0.0"
  },
  "paths": {
    "/v2/books": {
      "get": {
        "summary": "List all books",
        "responses": {
          "200": {
            "description": "A list of books"
          }
        }
      }
    }
  }
}

That is a minimal spec. It says: “There is a GET /v2/books endpoint. When you call it, you get a 200 response with a list of books.” It is simple enough for a human to read, but structured enough for a machine to parse. That second part is what makes it powerful.

Why machine-readable matters

A hand-written README is for humans only. Someone reads it, understands it, and then writes code based on what they read. An OpenAPI spec is for humans and machines. And that opens up an entire ecosystem of tooling.

Documentation UIs. Tools like Swagger UI and Scalar read the spec and render it as a beautiful, interactive web page. Clients can browse your endpoints, see the schemas, and even try out requests directly from the browser. No code required.

Client generation. Tools like openapi-typescript read the spec and generate TypeScript types and API client code. Your frontend developers get full autocompletion and compile-time type checking for every API call, without writing a single type definition by hand.

Testing. Tools can verify that your API’s actual responses match what the spec says. If the spec says the response has a title field but the API returns name instead, the test fails.

Mocking. Frontend teams can generate a fake server from the spec and start building their UI before you have even finished the backend. The mock server responds with realistic data based on your schemas.

Validation. API gateways can validate incoming requests against the spec before they even reach your server. Bad requests get rejected at the gate.

All of this comes from a single JSON file. Write the spec once (or better yet, generate it from your code), and you get documentation, types, tests, mocks, and validation for free. That is the power of a machine-readable format.

The structure of an OpenAPI spec

An OpenAPI spec has several top-level sections. You do not need to memorize all of them right now. We will build each one throughout this course. But here is the overall shape so you know where things live:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Book Catalog API",
    "version": "2.0.0"
  },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/v2/books": {
      "get": { "...": "..." },
      "post": { "...": "..." }
    }
  },
  "components": {
    "schemas": {
      "Book": { "...": "..." },
      "CreateBook": { "...": "..." }
    },
    "securitySchemes": {
      "bearerAuth": { "...": "..." }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "tags": [{ "name": "Books" }, { "name": "Reviews" }]
}

The paths section is where the action is. Every endpoint your API exposes lives here. The components section holds reusable definitions so you do not repeat yourself. The security section describes how clients authenticate. The tags section groups endpoints into logical sections. We will dig into each of these in the coming lessons.

Note that @hectoday/openapi currently inlines schemas directly in each operation rather than using components.schemas with $ref references. The structural overview above shows the general OpenAPI standard, which supports both approaches. You will see components.schemas in specs from other tools and hand-written specs. We will cover this in the component schemas lesson.

OpenAPI 3.1 vs 3.0

This course uses OpenAPI 3.1, which is the latest version. The main difference from 3.0 is that schemas in 3.1 are fully compatible with JSON Schema. Why does that matter? Because Zod schemas align with JSON Schema. That means the Zod schemas you already have can map cleanly to OpenAPI schemas without awkward workarounds. This is going to make our lives much easier when we get to the Zod-to-OpenAPI lesson.

Exercises

Exercise 1: Look at the minimal spec above. Identify the API title, version, the endpoint path, and the HTTP method. Make sure you can read it before moving on.

Exercise 2: Try adding a second endpoint by hand: POST /v2/books with a summary of “Create a book.” Follow the same pattern as the GET endpoint.

Exercise 3: Open the Swagger Editor (editor.swagger.io) and paste a minimal spec. See how it renders as interactive documentation. This is what your API will look like by the end of this course.