OpenAPI JSON Explained

5 min·Jul 15, 2026

AI Summary

An OpenAPI document describes a REST API: info and servers at the top, paths with operations in the middle, and reusable schemas and security schemes under components. Tools turn it into docs, mocks and SDKs.

OpenAPI 3.1 Specification (Starter)

A minimal but complete OpenAPI 3.1 document with one CRUD resource, reusable schemas and an API-key security scheme — a clean base for any REST API.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Items API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/items": {
      "get": {
        "operationId": "listItems",
        "summary": "List items",
        "responses": {
          "200": {
            "description": "A list of items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Item"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createItem",
        "summary": "Create an item",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewItem"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Item": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "NewItem": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

An OpenAPI document is a single JSON (or YAML) file that fully describes a REST API. Once you know its four regions, it reads easily.

1. Metadata

{ "openapi": "3.1.0", "info": { "title": "Items API", "version": "1.0.0" } }

openapi — the spec version.
info — human metadata: title, version, description.

2. Servers

servers lists base URLs, usually one per environment. Clients prepend these to each path.

3. Paths and operations

paths is the heart of the document. Each key is a URL template; each HTTP method under it is an operation:

"/items": {
  "get": { "operationId": "listItems", "responses": { "200": { "description": "OK" } } }
}

Give every operation an operationId — code generators use it to name functions.

4. Components

components holds reusable pieces: schemas (data models), securitySchemes (auth), parameters and responses. Reference them with $ref:

"schema": { "$ref": "#/components/schemas/Item" }

Define a model once, reuse it everywhere.

Why it matters

From one OpenAPI file you can generate interactive docs, server stubs, typed client SDKs and mock servers. That is why "contract-first" API design starts here.

Open the OpenAPI starter template and ask the workspace to "add a DELETE operation" or "add pagination" — then review the change as a diff.

FAQ

What is the difference between OpenAPI and Swagger?

Swagger was the original name; OpenAPI 3.x is the current standard. "Swagger" now usually refers to the tooling (Swagger UI, Swagger Editor).

Why use $ref?

To define a schema once under components and reuse it across many operations, keeping the document DRY and consistent.