An OpenAPI document is a YAML or JSON file that describes your HTTP API: its servers, its paths, the operations on each path, the parameters they take, the schemas of what goes in and comes out, the responses and status codes, and the security schemes required to call it.
The reason to have one is leverage. A single OpenAPI document is the input to your reference documentation, your mock server, your contract tests, your SDK generation, your gateway configuration, your governance linting, your Postman collection, your API catalog entry, and increasingly your MCP server and your agent tooling. Every one of those things is work someone would otherwise do by hand, inconsistently, and let drift.
It is also the most effective API literacy tool I have ever found. Sitting a team down in front of the OpenAPI for what they just built produces a very specific kind of silence, because the document does not let you be vague. Either the endpoint is defined or it is not. Either the schema is right or it is not.
Two warnings. A generated-from-code OpenAPI that nobody reads is a fossil, not a contract — it records what the code happens to do rather than what you promised. And an OpenAPI that lives only in a wiki attachment is not an artifact; put it in version control next to the code, and lint it in the pipeline.
