API strategy
Agent infrastructure
What is OpenAPI? A deep-dive on the specification, the ecosystem, OpenAPI vs Swagger, and what changes when AI agents — not humans — read the spec.
OpenAPI is the machine-readable contract that describes what an HTTP API does, how to call it, and what it returns. It is the closest thing the web has to a lingua franca for describing REST APIs — and in 2026, it is also the artefact that agent tooling reaches for first when it needs to know what a product can do.
That matters more than it used to. When the primary reader of your spec was a human developer, sloppy descriptions and missing examples were an annoyance. When the reader is an SDK generator or an AI agent, the same gaps decide whether the tool works at all. This deep-dive walks through what OpenAPI actually is, how it got here, what the spec includes, where the ecosystem sits, how it compares to Swagger, and what changes when agents — not humans — are the primary consumer.
OpenAPI started life as Swagger, a specification and toolchain built at Wordnik around 2010. In 2015, SmartBear donated the Swagger Specification to the newly formed OpenAPI Initiative, an open-governance project under the Linux Foundation. The specification was renamed the OpenAPI Specification (OAS). Swagger stayed as the brand for the tools SmartBear ships around it — Swagger UI, Swagger Editor, Swagger Codegen.
The naming has caused years of confusion, so it is worth being blunt about it. OpenAPI is the specification — the format you write your API description in. Swagger is a family of open-source tools that read and write that format. When someone says "our Swagger docs," they almost always mean "our OpenAPI-described docs, rendered by Swagger UI." The file itself is an OpenAPI document.
The spec has moved through 3.0 (2017), 3.1 (2021, which aligned with JSON Schema draft 2020-12), and 3.2 (2025). Most of the ecosystem now runs on 3.0 or 3.1. The differences between 3.0 and 3.1 are meaningful — full JSON Schema alignment, webhooks as first-class, null handled properly — but the mental model has stayed stable: describe your API declaratively, in YAML or JSON, and let tools do the rest.
An OpenAPI definition is a single document (or a set of documents linked with $ref) that describes an HTTP API. The top-level structure is the same whether the file is 200 lines or 20,000.
The root object contains a few required fields — openapi (the version), info (title, version, description), and paths (the endpoints). It also carries servers (base URLs and environments), components (reusable schemas, parameters, responses, security schemes), security (which schemes apply globally), tags (for grouping), and, since 3.1, webhooks (server-initiated callbacks).
Inside paths, each endpoint lists its HTTP methods. Each method describes its parameters (path, query, header, cookie), request body (with content types and schemas), responses (keyed by status code, each with content types and schemas), security requirements, and — critically — a summary, description, and operationId. Those three fields are the ones agents read most closely. A well-written description on an operation is often the difference between an agent picking the right endpoint and picking the wrong one.
Schemas inside components/schemas are where the data model lives. In 3.1, these are full JSON Schema — oneOf, anyOf, allOf, discriminator, nullable (deprecated in favour of type: ["string", "null"]), constraints, examples, defaults. This is also where OpenAPI stops being just documentation and becomes something a code generator can compile: types on both sides of the wire, validation rules, error shapes.
A good OpenAPI document is not a wall of endpoints. It has descriptions on every operation, examples on every request and response, operationId values that read like sentences, and tags that group endpoints into workflows. Bad documents have none of these. Both validate. Only one is useful.
The question "OpenAPI vs Swagger" comes up so often it is worth handling directly. They are not competing specifications. Swagger 2.0 was the last version of the specification released under the Swagger name. Everything after that — 3.0, 3.1, 3.2 — is OpenAPI. If a file's root has swagger: "2.0", it is Swagger 2.0. If it has openapi: "3.x.x", it is OpenAPI.
The substantive differences between Swagger 2.0 and OpenAPI 3.x matter if you are still on 2.0:
If you are writing a new spec in 2026, write OpenAPI 3.1. The 3.0 → 3.1 upgrade is usually mechanical, and the JSON Schema alignment saves real pain when your consumers include SDK generators and agent tooling that already speak JSON Schema natively.
The Swagger tools themselves — Swagger UI, Swagger Editor, Swagger Codegen — are still widely used and still open source. They read OpenAPI 3.x fine. You will see them referred to as Swagger tools for the rest of their lives. That is fine. Just do not confuse the tools with the spec.
The reason OpenAPI matters is not the file format. It is what the file format unlocks.
Documentation. Swagger UI, Redoc, Scalar, Stoplight Elements — all render an OpenAPI document into interactive reference docs. This is the single most common use, and it is what most developers think of when they hear "OpenAPI."
SDK generation. Stainless, Fern, Speakeasy, and the older open-source OpenAPI Generator all consume OpenAPI and emit typed client libraries in a dozen languages. The quality of the generated SDK is almost entirely a function of the quality of the source spec. Vague descriptions, missing examples, and loose types produce SDKs that developers immediately have to work around.
Server scaffolding and validation. Tools like FastAPI and Go's oapi-codegen will generate server stubs or runtime request/response validators from a spec. This is where "spec-first" development shows its value: the contract is the source of truth, and code has to conform.
Contract testing. Prism mocks an API from its spec so consumers can develop against it before the server exists. Schemathesis generates property-based tests directly from the spec. Both are how teams catch OpenAPI spec drift before it reaches production.
API gateways and management. Every major API gateway — Kong, Apigee, AWS API Gateway — can import OpenAPI to configure routes, auth, and rate limits. This is where OpenAPI stops being a docs artefact and starts being infrastructure config.
The honest trade-off: the ecosystem is huge and the specification is stable, which is good. It is also fragmented, and every tool interprets edge cases slightly differently. nullable, discriminator, oneOf with overlapping shapes, and deeply nested $ref chains are all places where two conformant tools will produce different output. If your spec has to work across five downstream tools, you end up designing to the intersection of what they support — not the union of what the spec allows.
Here is where the last five years of OpenAPI evolution start to matter differently. When the primary consumers were human developers and code generators, the spec's job was to be complete and consistent. When the primary consumer is an AI agent — either directly, or through an MCP server generated from the spec — the spec's job expands.
Three things break in ways they did not before.
Descriptions become executable. A human developer skims a description, forms a rough mental model, and figures out the rest from context. An agent reads the description as a specification of when to call the endpoint. "Creates a new user" is not enough. "Creates a new user in the specified organisation. Fails if the email address is already registered. Does not send an invitation email — use POST /users/{id}/invite for that" is the level of specificity an agent needs. This is why teams pushing OpenAPI toward agent use end up rewriting descriptions from scratch.
operationId becomes the tool name. SDK generators use operationId to name methods. Agent tooling uses it to name tools. listUsers is a fine method name and a bad tool name — the agent has no idea it lists users in an organisation. list_organisation_users reads better as a tool. This tension is real: what makes a good SDK method name is often not what makes a good agent tool name. You end up choosing an audience.
The whole spec is rarely the right tool surface. Most enterprise APIs have hundreds of endpoints. Loading all of them as agent tools blows out the context window, degrades tool selection accuracy, and exposes internal operations that were never meant for agent use. The right pattern is curation — using tags, custom extensions, or a separate manifest to pick the subset of endpoints that map to real workflows. We wrote about this in OpenAPI endpoint curation for MCP.
And underneath all of it, one problem gets worse: the spec has to match reality. OpenAPI spec drift — where the document says one thing and the running code does another — is annoying for humans and catastrophic for agents. A human developer notices the mismatch and works around it. An agent produces a tool call that looks valid, hits a runtime error, and stalls. The economic pressure to keep the spec accurate has just gone up by an order of magnitude.
This is the argument that never fully resolves. Both approaches produce the same file. The difference is where the source of truth sits.
Spec-first (design-first). Write the OpenAPI document by hand — usually with an editor like Stoplight Studio or a linter like Spectral. Generate server stubs, mocks, and tests from it. The spec is the contract; code implements it. Wins on: cross-team review, breaking-change detection, docs quality, consistency across a portfolio. Loses on: developer friction, drift when engineers change the code without updating the spec.
Code-first. Annotate your handlers (Python decorators, Go struct tags, C# attributes) and let the framework emit the spec. FastAPI, Spring, and .NET all do this well. Wins on: single source of truth, no drift by construction, low friction for engineers. Loses on: design discipline (the spec inherits every code decision, good or bad), consistency across a portfolio, review-ability before implementation.
Which approach fits depends on the shape of the organisation. Small teams shipping fast usually do better code-first. Large organisations with multiple products, portfolio-level API standards, and a partner or agent audience usually do better spec-first — or a hybrid where code-first drafts are reviewed and edited before publication. The OpenAPI specification best practices piece goes deeper on the trade-offs.
One pattern that has stopped working: treating OpenAPI as something you generate once, publish, and forget. In an agent-era product, the spec is a live artefact. It ships with every release, gets diffed in CI, and gets consumed by tools you do not always control.
Pontil sits in the tools layer of the agent stack — the layer that turns a product's capabilities into things an agent can actually invoke. OpenAPI is the natural starting point for that work, but it is not the whole story. A spec describes the API you have; agents need tools for the workflows your product supports. Those are rarely the same thing.
We generate tools from existing codebases, whether or not a clean OpenAPI document exists, and we run them through a managed runtime that executes as the authenticated user rather than a shared service account. That means the spec becomes one input among several — useful, but not required, and never the ceiling on what agents can reach. If you want to see how we approach the gap between an API spec and an agent-ready surface, our product page walks through the model.
The honest answer is: probably OpenAPI, for a long time. The spec is stable, the ecosystem is deep, and no serious alternative has emerged. Protocol layers like MCP sit on top of API descriptions — they do not replace them. AsyncAPI covers event-driven surfaces that OpenAPI historically did not, and 3.1's webhook support has closed some of that gap. GraphQL is its own world with its own schema language, and it is not going to displace OpenAPI in REST-heavy enterprises.
The more interesting question is what the readers of the spec look like in five years. If most OpenAPI documents are being read by SDK generators, doc renderers, and agent runtimes — not human developers — then the design conventions that made specs pleasant for humans start to matter less than the ones that make them reliable for machines. Precise descriptions, accurate examples, tight schemas, and honest error models are going to matter more. Cleverness is going to matter less.
That shift is already happening, and it will keep going. The teams that treat their OpenAPI document as a first-class product artefact — versioned, tested, reviewed, and kept in sync with reality — are the ones whose agents will actually work.
Stay up to date on the ever changing agentic landscape.
GET STARTED
Start with a 30-minute discovery call
contactus@pontil.com
