The State of OpenAPI 3.2 Support

An API Evangelist Paper on which documentation platforms, gateways, SDK generators, clients, parsers, linters and server frameworks can read, render and write OpenAPI 3.2, one year after it shipped, and what API providers and tooling vendors should do about it

By Kin Lane, the API Evangelist · Version 1.0 · October 2026
_{Status as of the 2026-10-08 tooling census. Version support changes with every release, and several projects named here have 3.2 work in flight. Every verdict is a snapshot with evidence behind it, and this paper is updated on a regular cycle.}

Executive summary

OpenAPI 3.2 was released on 19 September 2025. It is the first feature release of the specification since 3.1 in 2021. It adds things API providers have asked for over many years: a QUERY method, room for operations outside the fixed list of HTTP methods, a way for a document to name its own location, schemas for streamed items, and tags that can be grouped into a hierarchy.

A specification is only as useful as the tooling that can read it. An API provider can write a perfect 3.2 document today. The question is what happens when that document reaches the docs platform, the gateway, the SDK generator, the linter in the CI pipeline and the MCP server builder. So API Evangelist research went and found out.

The census covers 137 tooling subjects, 133 of which touch OpenAPI. Fifty tools that run on a laptop were fed the same set of test documents and judged on what came out. Eighty-seven hosted products and frameworks were read from their own documentation, changelogs, source and issue trackers. Every verdict carries a fetched URL and quote, a probe command and its output, or a source file.

The headline, one year in:

• 33 of 133 (25%) handle a 3.2 document. Only 15 of them say so themselves. The other 18 passed the test document through intact without making any claim.
• 18 (14%) are partial. They accept the version string and drop some of the new constructs. This is the most common real state in the market.
• 30 (23%) reject 3.2, by name in an error message, in their documentation, or in an open issue.
• 52 (39%) are unknown. Among hosted vendors, that is 36 of 56. Their pages list 3.0 and 3.1 and say nothing about 3.2.

Two findings matter more than the totals. First, a small number of shared parsers decide what a large part of the market can read. When one parser rejects 3.2, every CLI, code generator and MCP builder built on top of it rejects it too. Second, 3.1 is not finished either. Twenty-four subjects show no 3.1 support at all, five years after it shipped. Version adoption in this market is set by framework defaults and shared libraries, not by the specification’s release date.

The paper walks it in this order:

1. What 3.2 adds, and why the additions are worth wanting.
2. How the census was measured, including the three times the harness got it wrong.
3. The numbers, by class of tool.
4. Who states support: the fifteen that wrote it down.
5. Partial is the market: accepting the string and losing the meaning.
6. Where 3.2 stops by name, and the parser chains that explain it.
7. The silence: why most hosted vendors are unknown.
8. 3.1 is not finished, and what frameworks emit by default.
9. The neighbours: AsyncAPI, Arazzo and Overlay.
10. What to do, for API providers and for tooling vendors.

1. What 3.2 adds, and why it is worth wanting

OpenAPI 3.1 was the alignment release. It brought schemas into line with JSON Schema 2020-12 and added webhooks. OpenAPI 3.2 is a practical release. Most of what it adds closes a gap that providers had been working around with vendor extensions.

The census test document for 3.2 exercises six of those additions:

Each of these makes a contract more accurate. Streaming descriptions matter more every month, because so much of the API traffic being built now is model output delivered as events. Tag hierarchies matter for any provider with more than a few dozen operations. A contract that says what it actually does is the thing an agent needs most.

None of it is useful unless the tools that consume the contract understand it. That is what the census set out to measure.

2. How the census was measured

The method came from one rule: a version claim needs evidence. That means a fetched URL with a quote, a probe command with its output, or a source file. A product whose documentation lists 2.0, 3.0 and 3.1 and does not mention 3.2 is recorded as unknown, never unsupported. Silence is not a rejection.

Fixtures

Every runnable tool received the same nine documents: Swagger 2.0, OpenAPI 3.0.3, OpenAPI 3.1.0 with 3.1-only constructs, two OpenAPI 3.2.0 documents, AsyncAPI 2.6 and 3.0, Arazzo 1.0.1 and Overlay 1.0.0.

The two 3.2 documents are the key to the method. The plain one is a valid 3.0-style document with only the version string changed to 3.2.0. The features one uses the six additions above. Many tools are version-tolerant. They accept any version string and quietly ignore what they do not understand. Two fixtures separate a tool that understands 3.2 from a tool that merely does not object to it.

Verdicts

• Supported: the tool accepted the features document and its output still contained the QUERY operation, or the vendor states support in its own documentation, changelog or source.
• Partial: the tool accepted the version and lost some of the new constructs, or the vendor states support for some 3.2 constructs and not the whole version.
• Unsupported: the tool rejected 3.2, or the vendor says it does not support it.
• Unknown: no evidence either way.

Where both a probe and a documentation page exist, the probe outranks the page and the census table shows both, so any disagreement is visible.

What the harness got wrong first

The harness mis-scored three times before the numbers could be trusted. Each mistake is a lesson for anyone testing their own toolchain.

1. Exit code 0 is not acceptance. One code generator wrote an empty file for a Swagger 2.0 input and exited cleanly. The runner now requires the fixture’s operation to appear in the output.
2. Linters fail on style. Spectral, vacuum and Redocly all exited with errors on a missing info.description, so every version looked rejected. Linters are now judged only on errors that mention the version.
3. Pinned library versions go stale. The Go probes first ran against kin-openapi 0.132 and libopenapi 0.25. At current releases, kin-openapi is partial and libopenapi is fully supported. A census is only as current as its dependency file.

What was not covered

Hosted products were read, not exercised. Nobody uploaded a 3.2 document into fifty-six import flows. Java and .NET tools were judged from source and changelogs rather than executed. Two CLIs could not run in the harness and were judged from their documentation and parsers. Those limits are why unknown is the largest class, and they are where the next edition starts.

3. The numbers

Two readings follow directly from the table.

Open-source tools are the best-measured class and the best-supported one. Only 6 of 50 are unknown, because most of them could be run. Nineteen handled the features document. When a tool can be tested, there is usually an answer, and the answer is often good.

Hosted vendors are the least known. Thirty-six of fifty-six have no evidence either way. That does not mean they fail. It means their public documentation does not say, which leaves a provider with no way to find out short of trying it.

For context on the older versions across all 133: 68% consume 3.0, 57% consume 3.1, 56% still consume Swagger 2.0, and 27% consume 3.2. On the emitting side, 30% write 3.0, 25% write 3.1, 13% still write Swagger 2.0 and 11% write 3.2.

4. The fifteen that wrote it down

Fifteen subjects state 3.2 support in their own documentation, changelog or source as of October 2026. They deserve to be named, because a public statement is what lets a provider plan.

The pattern is worth noticing. The quickest movers were the projects closest to the specification: libopenapi had support within days of the release. Next came documentation renderers, whose whole job is showing a document to a person. The frameworks followed in 2026, mostly in the last few months. The gateways and API management platforms are not on this list at all.

The eighteen that passed it through

Another eighteen tools accepted the features document and kept the QUERY operation without claiming 3.2 support anywhere: Redocly CLI and the Redoc build, vacuum, oasdiff, Prism, openapi-format, swagger2openapi, openapi-down-convert, Postman’s openapi-to-postman converter, Kong’s decK, Bump’s CLI, prance, openapi-core, openapi-spec-validator, swagger-client, Sourcey, widdershins and Scalar’s parser.

This is good news with a caveat. A tool that keeps the QUERY operation in its JSON output is not necessarily drawing it on the page or generating a method for it. Passing through is the floor of support, and for transformation tools like openapi-format or openapi-down-convert it is the whole job. For a renderer or a mock server, it is the start of the job.

5. Partial is the market

Eighteen subjects are partial, and in practice this is where most of the market sits. They read a 3.2 document. They do not read all of it.

• Postman: the converter handles 3.2, while the Spec Hub documentation still lists 2.0 through 3.1.
• Kong: decK routes the QUERY method and drops additionalOperations.
• Speakeasy states that it supports “selected 3.2 constructs, not yet a complete document version.”
• Stoplight, Redocly’s hosted Redoc, Yaak, mkdocs and Docusaurus each support part of the version.
• hey-api, orval, oapi-codegen, openapi-typescript and kin-openapi load the document and lose some constructs.
• NestJS added the 3.2 fields in 11.4.0, while its document still says 3.0.0 unless setOpenAPIVersion('3.2.0') is called.
• LangChain and LlamaIndex load 3.2 and silently ignore what they do not know.

Partial support is a reasonable engineering choice. Shipping the constructs that customers ask for first is how most of these projects work. The risk is for the provider. A partial tool does not fail loudly. A provider who adds a QUERY operation can see the document import cleanly, and then find the operation missing from the generated SDK or the agent’s tool list. The LangChain and LlamaIndex case matters most here, because an agent that never sees an operation cannot tell anyone it is missing.

6. Where 3.2 stops by name

Thirty subjects reject 3.2 outright. Most of them say exactly why, which is more useful than silence.

The most important finding in this section is that a few shared parsers decide what a large part of the market can read:

• swagger-parser for JavaScript reports that it “only supports versions 3.1.0 … 3.0.4.” swagger-cli, orval and openapi-mcp-generator are built on it, so they reject 3.2 as well.
• swagger-parser for Java does not accept 3.2, and OpenAPI Generator is built on it. OpenAPI Generator is one of the most widely used SDK generators in the market.
• Spectral’s oas3-schema rule requires a version matching ^3\.0, so the most common open-source linter flags a 3.2 document.

When one of these libraries ships 3.2, a whole branch of the market moves with it. That makes them the highest-leverage place for anyone who wants 3.2 adopted, including the specification community, to spend effort.

The rest of the explicit rejections, as stated by the products themselves or by open issues:

• ReadMe: “OpenAPI 3.2 is currently unsupported,” with a full 3.2 pull request in draft.
• Fern CLI: “Unsupported OpenAPI version: 3.2.0.”
• openapi-python-client, FastMCP, Connexion, oas-kit and ReadMe’s open-source parser.
• Insomnia and Bruno: open issues requesting support.
• Azure API Management: documentation dated 2026-06 says it “only supports … 3.1 import-only.”
• AWS API Gateway HTTP APIs: “only the OpenAPI 3.0 specification.”
• Frameworks: springdoc, Swashbuckle, NSwag, tsoa, Hono, Elysia and grape-swagger.

Several of these have 3.2 work under way. A draft pull request or an open issue is a signal that the version is coming. The census records the state on 8 October 2026, not a verdict on where these projects are heading.

7. The silence

Thirty-six of fifty-six hosted vendors are unknown. Among them are GitBook, Apigee, APIMatic, Tyk, WSO2, Zuplo, Boomi, Stainless, liblab, Sideko, Apidog, RapidAPI and Cloudflare API Shield, plus every MCP host and agent platform the census looked at. Their pages name 3.0 or 3.1 and stop there.

No vendor writes “we do not support 3.2.” They simply do not mention it. That is understandable, because documentation pages are written once and updated when something ships. But it puts the work of finding out onto every one of their customers separately.

This is the cheapest gap in the whole census to close. A single line on an import page, saying which versions are accepted, partially accepted and on the roadmap, would move a vendor from unknown to known overnight. It does not require shipping anything. It is also the kind of evidence an agent can read when it is deciding which tool can handle a document.

The MCP and agent platforms are worth a separate note. They are the newest consumers of OpenAPI and the ones growing fastest. Many of them turn an OpenAPI document into tools for an agent. Not one of the platforms examined states which OpenAPI versions it reads.

8. 3.1 is not finished, and frameworks decide

It would be easy to read the 3.2 numbers as a story about a new release that has not caught on yet. The 3.1 numbers say otherwise. Twenty-four subjects show no 3.1 support at all, in or out, five years after it shipped:

• Gateways and API management: IBM API Connect (“Version 3.1 is not supported,” under future consideration), MuleSoft (2.0 or 3.0), AWS API Gateway (2.0 and 3.0 in and out), Axway, Gravitee and Solo.io.
• Older tooling: Apiary (Swagger 2.0 only, reaching Oracle’s end of life on 2026-10-31), RapidAPI’s importer (2.0 and 3.0.0–3.0.2), Swagger Codegen and NSwag.
• Frameworks: Connexion, grape-swagger, OpenApiSpex, rswag, Goa (2.0, 3.0 and 3.2, skipping 3.1), and NestJS’s default document.

Others support 3.1 with conditions. Azure imports it and downgrades it. Tyk describes its 3.1 support as “basic.” Boomi, WSO2 and Cloudflare each document gaps.

The version a provider publishes is usually not a decision. It is whatever the server framework emits by default:

Only one framework defaults to 3.2: ASP.NET Core on .NET 11. Everywhere else, 3.2 is opt-in or not available. The Python and Rust generation defaults to 3.1. Many of the Node, Java and .NET incumbents default to 3.0, and four widely used frameworks still default to Swagger 2.0.

This matches what API Evangelist found on the provider side of the market, where roughly one in ten API providers in the catalog still publishes Swagger 2.0. Providers are not choosing old versions. Their frameworks are choosing for them, and most providers never change the default. The quickest way to move the whole market forward a version is to change the defaults in a handful of frameworks.

9. The neighbours: AsyncAPI, Arazzo and Overlay

The census tested the other specifications an OpenAPI toolchain increasingly depends on.

• AsyncAPI 3.0 is read by Kong Konnect, Backstage, Redocly, Fern, Mintlify, Postman Spec Hub, WSO2 (which also emits it), Spectral, widdershins and the AsyncAPI tooling itself. Bump.sh, Stoplight and MuleSoft stop at 2.x. Apigee, Gravitee and IBM accept AsyncAPI without stating a version.
• Arazzo 1.0 is consumed by Redocly, Speakeasy, Spectral, Stoplight, Bump.sh and libopenapi, with 1.1 in libopenapi and Redocly. No gateway, portal or MCP host touches it. That is a gap worth noting, because Arazzo describes exactly the multi-step workflows agents need.
• Overlay 1.0 is applied by Bump.sh, Mintlify (1.0 and 1.1), Redocly (through 1.2), Speakeasy, libopenapi, openapi-format and openapi-overlays-js. All four open-source implementations applied the census fixture correctly.

Overlay is the quiet success in this census. It is young, it is narrow, and the tools that claim it actually do it.

10. What to do

If you publish an API

1. Know your default. Find out which OpenAPI version your framework emits and whether it can emit a newer one. Most providers have never checked.
2. Publish 3.1 as your baseline. It is the version the largest share of current tooling reads in full. If you are still on Swagger 2.0, moving to 3.1 is the most valuable step available to you.
3. Use 3.2 where it earns its place, and test the chain. If you stream responses or need QUERY, 3.2 describes your API more honestly than any earlier version. Before you switch, run the document through every tool downstream of you: docs, gateway, SDK generator, linter, MCP builder. Check the output for the new operations, not just the exit code.
4. Keep a down-converted copy if you need one. openapi-down-convert handles 3.2 and can produce a 3.0 or 3.1 copy for the consumers that need it. Publish the most accurate version as the source of truth and generate the others from it.
5. Do not trust a clean import. Partial support fails silently. Check that the operations and schemas you care about survived.

If you build API tooling

1. State your versions. Put the versions you accept, partially accept and plan to support on your import page. It costs one sentence, and it moves you out of the largest and least useful class in this census.
2. Fail loudly. If you drop a construct, say so in a warning. A tool that names what it ignored is more useful than one that pretends it understood.
3. Watch your parser. If you depend on swagger-parser, Spectral’s schema rules or a similar shared library, its version support is your version support. Track it, and contribute upstream where you can.
4. Change the default when you can. Framework maintainers have more influence over the market’s version than any other group in this census.

11. Anti-patterns worth watching for

• Treating exit code 0 as success. A tool that writes an empty file and exits cleanly has not accepted your document.
• Assuming silence means support. Most hosted vendors do not mention 3.2. That is not a yes.
• Assuming silence means rejection. It is not a no either. Test it, or ask.
• Adopting a version without checking the chain. The document is only as readable as the least capable tool downstream of it.
• Accepting the string, dropping the meaning. Version-tolerant parsing is useful, but losing an operation without a warning hides a defect from the people who would fix it.
• Leaving the framework default alone for years. The version you publish should be a decision, not an accident of what your framework shipped with.
• Pinning a parser and forgetting it. The census itself produced the wrong verdicts from library versions a few months old.
• Building agent tooling with no version statement. The fastest-growing consumers of OpenAPI are the least clear about what they read.

12. Self-assessment

As an API provider

• Do you know which OpenAPI version your server framework emits by default?
• Is your published contract on 3.1 or later?
• Have you listed every tool downstream of your contract: docs, gateway, SDK generator, linter, mock server, MCP builder?
• Do you know which version each of those tools reads in full?
• When you change versions, do you check the output for your operations, not just for errors?
• If you stream responses or need QUERY, have you evaluated 3.2 for those operations?
• Do you publish a down-converted copy for consumers that cannot read your source version?

As a tooling vendor or maintainer

• Does your documentation state which OpenAPI versions you accept, partially accept and plan to support?
• Does your tool warn when it ignores a construct it does not understand?
• Do you know which shared parser decides your version support, and which version of it you ship?
• If you maintain a framework, is your default the most current version you fully support?
• Have you tested your import flow with a 3.2 document that uses the new constructs, not just the new version string?

13. Where this is going

The pattern in this census is not new. Swagger 2.0 to OpenAPI 3.0 took years. 3.0 to 3.1 is still not complete. 3.2 is following the same curve, led by renderers and the libraries closest to the specification, with frameworks catching up in 2026 and gateways last.

What is new is who reads the document. For most of OpenAPI’s history the main consumers were documentation renderers and code generators, and a human sat between the contract and the integration. Increasingly the consumer is an agent platform turning operations into tools. Those platforms are the least explicit about the versions they read, and the most likely to drop a construct without telling anyone. A streaming operation described with itemSchema is exactly the kind of thing an agent needs to understand. Right now, few of the tools in an agent’s path would pass it along.

The fix is straightforward and mostly does not need new code. Tooling vendors can state their versions in a form a person or a machine can read. Shared parsers can ship 3.2 and lift everything built on them. Frameworks can move their defaults forward. Providers can treat their OpenAPI version as a decision and test the whole chain before they change it.

The next edition of this census will upload a 3.2 document into each hosted vendor’s import flow, run the Java and .NET tools directly, and record each vendor’s stated versions as structured data in the APIs.io catalog, so the answer to “can this tool read my contract?” can be looked up rather than researched.

Appendix A. Verdicts by subject (selected)

The full census of 137 subjects, with the evidence behind each row, is maintained by API Evangelist research and feeds the tooling records in the APIs.io catalog.

Appendix B. The census fixtures

About API Evangelist

API Evangelist is the research, analysis, and advisory practice of Kin Lane, studying the business and politics of the API industry since 2010. For sixteen years it has been one of the most cited independent voices in the space, publishing open research at apievangelist.com and maintaining a working catalog of the API landscape at APIs.io.

The practice is deliberately independent and vendor-neutral. Kin is a former Presidential Innovation Fellow and has advised platform teams, enterprises, and government agencies on API strategy, governance, and developer experience. The analysis in this paper was built in the field, by running the tooling the API market depends on against the same set of contracts and recording what each one actually did, then stripped of anything proprietary and rebuilt as guidance any team can use.

About API Evangelist White Papers

API Evangelist White Papers are formal, practitioner-focused guides distilled from ongoing research and field work across the API landscape. Each one takes a consequential piece of API operations, like the specification versions your toolchain can read, and turns hard-won experience into an opinionated, reusable playbook, complete with anti-patterns and a self-assessment you can run against your own operations.

They differ from a typical blog post or vendor white paper in three ways:

• Experience-based. The recommendations come from doing the work at scale, not from a vendor’s feature list.
• Vendor-neutral. No sponsor steers the conclusions; tools and providers are named on merit.
• Living documents. Each paper carries a version and an “as of” date, and is revised on a regular cycle as the landscape moves.

API Evangelist Services

This paper is a map; API Evangelist also does the work alongside you. Engagements draw on the same practice behind these papers and are organized into three areas — discovery, governance, and evangelism — each made up of focused, repeatable engagements you can mix and match.

• Discovery — map the words, interfaces, and standards that define what your operations actually need: Vocabulary, Interfaces (your OpenAPI and the rest), and Standards, including which specification versions your contracts and your toolchain should be on.
• Governance — define and iterate on the Strategies, Experiences, Policies, Rules, Pipelines, Skills, and Reviews that keep contract versions a decision rather than a framework default.
• Evangelism — craft and publish the Stories, Conversations, Talks, Research, Papers, and Workshops that tell the story of your work — the same practice that produced this paper.

Get in touch

If you’d like to go deeper on anything here, such as a version audit of your contracts and the toolchain downstream of them, a migration plan from Swagger 2.0 or 3.0 to 3.1 or 3.2, or a statement of version support for your own tooling product, API Evangelist welcomes the conversation.

• Email: [email protected]
• Web: apievangelist.com · Services: services.apievangelist.com
• Catalog: APIs.io

— Kin Lane, the API Evangelist

_{© API Evangelist · Kin Lane · This paper is part of a regularly-updated series.
Each section is also published as a standalone post at apievangelist.com.}