Spec Structure

## What an OpenAPI document actually is An OpenAPI description is a single structured document — one JSON or YAML object, conventionally named `openapi.yaml` or `openapi.json` — that describes an HTTP API in a machine-readable way. Everything in it hangs off a small set of root keys. Knowing those keys by heart is what lets you open an unfamiliar 4,000-line spec, jump straight to the part you need, and review a diff without a generator in the loop. ## The two keys that are always required `openapi` is a string holding the version of the *specification* the document conforms to, such as `"3.0.3"` or `"3.1.0"`. It is not the API's version. Tooling reads it first to decide which rules apply, so a wrong value here makes the whole file unparseable. `info` is metadata about the API itself. It requires `title` and `version` (the API's version — often a semver string tied to your release train). Optional members include `description`, `termsOfService`, `contact` and `license`. OpenAPI 3.1 additionally allows `info.summary` and a `license.identifier` field carrying an SPDX identifier, mutually exclusive with `license.url`. ## Where the API is reachable: servers `servers` is an array of Server Objects. Each has a `url` — which may be relative and may contain `{variable}` placeholders — plus an optional `description` and a `variables` map. Each server variable declares a required `default` and optionally an `enum` of allowed values, which is how one document describes prod, staging and regional hosts without duplication. If `servers` is absent or empty, the effective value is a single server whose url is `/`, meaning "the host this document was served from". `servers` may also appear on a Path Item or an individual Operation, overriding the root value for that scope. ## The API surface: paths `paths` is a map from a templated path such as `/orders/{orderId}` to a Path Item Object. Keys must begin with `/` and are appended to the server URL. A Path Item Object holds an optional `summary` and `description`, the eight HTTP method fields (`get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`), a `parameters` list shared by every operation under that path, its own `servers` override, and may itself be replaced wholesale with a `$ref`. In 3.0, `paths` is required — even an empty object. In 3.1 it became optional, because a valid 3.1 document may describe only `webhooks`, or act purely as a shared `components` library. ## The reuse registry: components `components` holds named, reusable objects that have no effect unless referenced: `schemas`, `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links` and `callbacks`; 3.1 adds `pathItems`. Component names must match `^[a-zA-Z0-9._-]+$`. Putting a schema in `components.schemas` does not publish an endpoint — it only makes the definition addressable. ## The cross-cutting roots `security` lists security requirements that apply to every operation by default; an operation can override or opt out. `tags` declares the tag names used to group operations, with descriptions and ordering that documentation renderers honour — operations reference tags by name, and undeclared tags still work but render without a description. `externalDocs` points at prose documentation. OpenAPI 3.1 adds two roots: `webhooks`, a map of named out-of-band operations the API *sends* to the consumer, and `jsonSchemaDialect`, which declares the default JSON Schema dialect for Schema Objects in the document. ## Extensions Anywhere the specification allows it, keys beginning with `x-` are specification extensions. Vendor tooling stores configuration there (code generators, gateways). Unknown non-`x-` keys, by contrast, are simply invalid and good linters will fail the build on them. ## Why this is asked A candidate who has only ever generated a spec from annotations tends to describe it as "whatever Swagger produces". A candidate who edits specs by hand can say where a new endpoint goes, why the schema lives under `components.schemas`, and why moving a host into `servers` is a one-line change rather than a search-and-replace across the file.