# OpenAPI Specification The OpenAPI Specification (OAS) is a standard, language-agnostic way to describe an HTTP API in a single machine-readable document. You write one YAML or JSON file that says what endpoints exist, what each one accepts, what it returns, and how to authenticate. From that one description, tools can generate documentation, client and server code, mocks, and tests, all without anyone reading the source. The point is to treat the API as a **contract** that humans and machines agree on, instead of prose in a wiki that drifts out of date the moment someone ships a change. ## A bit of history It started life as **Swagger**, created by Tony Tam around 2010. In 2015 the project was donated to the OpenAPI Initiative under the [[Linux Foundation]] and renamed OpenAPI. "Swagger" now refers to the tooling (Swagger UI, Swagger Editor, Codegen) rather than the spec itself. ## What's in a description An OpenAPI document is organized around a few core pieces: - **`paths`** — the endpoints (`/users/{id}`) and the operations on them (`get`, `post`, `put`, `delete`). - **`parameters` and `requestBody`** — what each operation takes, by path, query, header, or body. - **`responses`** — the status codes and the shape of what comes back. - **`components/schemas`** — reusable data models, referenced with `$ref` so you don't repeat yourself. - **`securitySchemes`** — how callers authenticate (API key, OAuth2, bearer token, etc.). - **`servers`** — the base URLs the API lives at. The current major line is **3.x**. Version 3.1 is the one to care about: it aligned OpenAPI's data model with JSON Schema (2020-12), so the schemas you write for your API are real JSON Schema, not a near-miss dialect. ## Why it matters A good OpenAPI document is the source of truth that everything else hangs off: - **Docs that can't lie.** Tools like Swagger UI and Redoc render the spec, so the docs always match the contract. - **Code generation.** Generate typed client SDKs and server stubs in dozens of languages from the same file. - **Mocking and testing.** Stand up a fake server from the spec before the real one exists, and run contract tests to catch breaking changes. - **Agent tooling.** This is the part I find most interesting right now. An OpenAPI document is a clean, structured description of a capability, so it's becoming a primary on-ramp for AI. [[FastMCP]] can turn an OpenAPI spec straight into an [[Model Context Protocol (MCP)|MCP]] server, and the [[Agentic Resource Discovery Specification (ARD)]] treats OpenAPI tools as first-class discoverable resources (and uses OpenAPI itself to define its own registry API). ## My Opinion If you're building an API and you're writing the spec after the fact (or not at all), you're doing it backwards. Design the OpenAPI document first, agree on it, then implement against it. It costs a little discipline upfront and saves you from the classic mess where the docs, the client, and the server all disagree. And now that agents are starting to consume APIs directly, a clean, well-described OpenAPI surface is quietly turning into one of the highest-leverage assets a product can have. Write it well, and both humans and machines can use your API without asking you how it works. ## References - https://www.openapis.org/ - https://spec.openapis.org/oas/latest.html - https://swagger.io/specification/ ## Related - [[FastMCP]] - [[Model Context Protocol (MCP)]] - [[Agentic Resource Discovery Specification (ARD)]] - [[Linux Foundation]]