{"canonical_url":"https://engineer.company/glossary/openapi/","content_markdown":"# OpenAPI\n\n## What it is\n\nOpenAPI is a standard format for writing down everything a caller needs to know about an HTTP\nAPI — its addresses, operations, inputs, outputs, errors and security — in one JSON or YAML file\nthat people and programs read alike. The standard itself is the OpenAPI Specification, often\nabbreviated OAS, and a file written to it is an OpenAPI description. The format began as the\nSwagger Specification, and that older name survives in tools built around it, such as Swagger UI.\n\nThe specification says it defines a \"standard, programming language-agnostic interface description\nfor HTTP APIs\". The aim it states is that a person or a program can learn what a service does\nwithout its source code, extra documentation or a capture of its network traffic. The entry document\nis recommended to be named `openapi.json` or `openapi.yaml`, and larger descriptions are often split\nacross several files joined by references.\n\nSwagger 2.0 was released in September 2014 and donated to the OpenAPI Initiative on\n31 December 2015. Version 3.0.0 followed in July 2017 under the new name, 3.1.0 in February 2021\nand 3.2.0 in September 2025.\n\nA description has a handful of top-level parts. `info` names the API and its version; `servers`\nlists where it runs; `paths` holds each address and, under it, one operation per HTTP method,\nwith its parameters, request body and possible responses. `components` collects what is reused:\ndata schemas, parameters, responses and the security schemes that say how a caller\nauthenticates. Since 3.1, a `webhooks` section can also describe requests the API sends to its\nconsumers. A minimal fragment:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n    title: Orders\n    version: 1.4.0\npaths:\n    /orders/{id}:\n        get:\n            operationId: getOrder\n            parameters:\n                - name: id\n                  in: path\n                  required: true\n                  schema:\n                      type: string\n            responses:\n                \"200\":\n                    description: One order\n```\n\nThe data shapes are written in a schema language. From 3.1 the Schema Object is a superset of JSON\nSchema Draft 2020-12; 3.0 used an extended subset of an older draft with additions of its own. JSON\nSchema describes one piece of data, while OpenAPI describes a whole HTTP API and borrows JSON Schema\nfor the pieces. Its neighbours describe other kinds of interface: AsyncAPI covers message-driven\nsystems, gRPC services are declared in [Protocol Buffers](https://protobuf.dev/) `.proto` files, and\na GraphQL server publishes its own schema.\n\n## Why it matters\n\nA description in a standard format is one file that many tools can read, each saving work a\nteam would otherwise do by hand. Reference documentation renders from it. Client\nlibraries in several languages are generated from it, so a frontend calls a typed function\nrather than assembling a URL. Mock servers answer from it, so a frontend can be built before\nthe backend exists. Gateways import routes from it, test suites validate traffic against it,\nand AI agents that call APIs read it to learn what is on offer.\n\nThat reach is also the risk. Every one of those tools trusts the file. A description that is\nwrong is worse than none, because the generated client compiles, the documentation looks\nauthoritative, and the mistake shows up at runtime in someone else's product.\n\nSo the main decision is where the description comes from. In design-first work, people write the\ndescription, review it as the contract and then build the server to match. The shape of the API\nis argued over before any code exists, which suits public APIs and teams that work in parallel.\nThe cost is that the description and the server are two things that can disagree. In code-first\nwork, the description is generated from the server's own types and annotations. It cannot\ndescribe a route the server lacks, but it is only as precise as those types, and the design\ndiscussion happens in code review rather than in a document. Either way, the description stays\ntrue only if a build checks it.\n\nMoving from 3.0 to 3.1 changed how schemas are written, because 3.1 adopted JSON Schema 2020-12.\nGenerators, validators and gateways each support their own range of versions, so the version a\nteam writes is limited by the oldest tool in the chain.\n\n## What it looks like in practice\n\nFiber carried one API at first, with validation written out by hand, endpoint by endpoint,\nand no single document that described its shape. The\n[HTTP layer moved to Huma v2](/portfolio/migrated-the-api-to-huma-v2-at-100-parity/), on\ntop of Fiber, so each endpoint is declared with input and output structs and the OpenAPI\ndescription is generated from those types; the documentation follows the code instead of ageing\nin a wiki. The two WebSocket endpoints stay on raw Fiber, outside Huma's request-and-response\nmodel. Scale is what makes that description matter: at 760 operations across 649 paths, it is\nin practice the only way anyone can read the API, so knowing it is complete matters more than\nit did at fifty. A CI check holds route parity at 100%.\n\nIn another project, the description is the middle link of a chain that runs from the database\noutward.\nThe database schema and its functions shape the Go types,\n[Huma emits the description, and what the frontend uses is generated from it](/portfolio/generated-the-api-contract-from-the-database-out/):\na typed TypeScript client of 44,076 lines, 61 mock handlers for the frontend's tests, and the\nlimits each form enforces. It answers drift between frontend and backend, which usually\nsurfaces as a 422 in the browser after the mismatch has shipped. A contract check in CI fails\nthe build on divergence, with a probe aimed at optional body fields, where\n\"missing\" and \"null\" get confused, and at query-parameter enums. What that costs is a\ngeneration step in the middle of everything, and a chain only as trustworthy as its\nleast-guarded link.\n\nThe [company's page on readiness for AI agents](/ai-ready/) applies the same reasoning to\nagents. An application that agents can use offers a described API: an OpenAPI document, an MCP\nserver where agents should call it directly, and OAuth metadata so an agent can act for a user\nwithout being given the password. The page classifies each recommendation rather than obeying\nit, and because the company's own site has no API, an API catalogue and OAuth metadata are two\nof the five it declined there.\n\n## Where it goes wrong\n\n**The description promises something the server does not do.** A hand-maintained description\nfalls behind: a new query parameter, a renamed field or an error code that only the server\nknows about. Generated clients then compile against a fiction. Generate the description from\nthe code, or keep it separate and validate real requests and responses against it in the test\nsuite, and compare the routes the server registers with the paths the description lists.\n\n**Each client regeneration renames half the methods.** Without an `operationId`, generators\ninvent method names from the path and the HTTP method, so moving a route renames the function\nevery caller uses. The specification requires each `operationId` to be unique and treats it as\ncase-sensitive. Set one on every operation, choose it as carefully as a public function name,\nand make a linter fail the build when one is missing.\n\n**Fields that may be null start rejecting null after an upgrade.** OpenAPI 3.0 marked them with\n`nullable: true`. In 3.1 that keyword is gone and the type becomes a list, and a validator that\nmeets a keyword it does not know usually ignores it. A 3.0 schema relabelled as 3.1 therefore\nrejects null wherever its author meant to allow it. Convert schemas with the OpenAPI Initiative's\nupgrade guide, which also covers `exclusiveMinimum` becoming a number:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**The examples fail their own schema.** The specification says an example should match its\nschema and leaves checking it to tools. A reader copies the example from the documentation and\ngets a 422; a mock server serves it, and the frontend is built against data the real API will\nreject. Validate every example in CI, as strictly as live traffic.\n\n**The public description maps the admin API.** One description generated from every route, and\nserved at a public address, lists internal operations and their schemas to anyone who asks.\nPublish one description per audience, generated with the internal operations filtered out. The\nspecification allows objects to be left empty or removed for exactly this kind of access\ncontrol.\n\n## Further reading\n\n- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — the latest version of the\n  standard, with every object and field defined and a history of each release.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) — the schema language that\n  OpenAPI 3.1 and later use for every request and response body.\n- [Upgrading from OpenAPI 3.0 to 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html) —\n  the OpenAPI Initiative's own list of schema changes, `nullable` among them.\n- [Huma: OpenAPI Generation](https://huma.rocks/features/openapi-generation/) — how the Go\n  framework used in the projects above derives a description from handler types.\n\n\u003chttps://engineer.company/glossary/openapi/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"What OpenAPI is, how one file can drive docs, clients and mocks, what it costs to keep that file true, and the mistakes that let it drift.","formats":{"gemtext":"https://engineer.company/glossary/openapi/index.gmi","gopher":"https://engineer.company/glossary/openapi/gophermap","html":"https://engineer.company/glossary/openapi/","json":"https://engineer.company/glossary/openapi/index.json","markdown":"https://engineer.company/glossary/openapi/index.md","pdf":"https://engineer.company/glossary/openapi/index.pdf"},"kind":"page","language":"en","title":"What is OpenAPI?","url":"https://engineer.company/glossary/openapi/","version":1}