Layla Zulfa
In the rapidly evolving landscape of API development, the specification is the contract that binds providers and consumers together. For years, the OpenAPI Specification (OAS) has served as the industry standard, moving through versions that have incrementally added power, flexibility, and nuance. However, a recent deep-dive audit reveals a sobering reality: while the specification evolves, the sprawling ecosystem of tooling—gateways, documentation portals, SDK generators, and frameworks—is struggling to keep pace.
While OpenAPI 3.2 was released in September 2025, a year later, the industry finds itself in a state of "specification limbo." For API providers, the message is clear: adopting the latest version of the standard is not just a matter of choice, but a potential risk to the reliability of downstream consumer tooling.
The State of the Ecosystem: A Quantitative Audit
To understand the gap between the specification and its real-world implementation, I conducted a comprehensive audit of 137 distinct products and projects across the API lifecycle. This included documentation platforms, developer portals, API management gateways, SDK generators, and the server frameworks that emit OpenAPI documents by default.
The goal was to answer a fundamental question: When a provider publishes a document, does the downstream tooling actually understand it, or is it merely "faking" compatibility?
My methodology was governed by two strict rules:
- Functional Recognition: A tool only receives a "supported" rating if it actually processes the operations within a document. Simply opening a file without error is not synonymous with full support.
- Transparency: If a documentation page lists support for versions 2.0, 3.0, and 3.1, but remains silent on 3.2, it is categorized as "unknown," not "unsupported."
The results are revealing. While OpenAPI 3.0 remains the ubiquitous "lingua franca" of the industry, supported by 91 of the 95 tools surveyed, the newer 3.2 standard is trapped in a precarious position. Only 36 tools currently demonstrate the ability to read 3.2 files, and of those, only a handful are fully compliant.
A Chronology of the 3.2 Rollout
The release of OpenAPI 3.2 on September 19, 2025, was met with industry excitement, promising better handling of complex operations and modern API patterns. However, the path from specification release to tool integration is rarely a straight line.
Year One: The "Silent Rejection" Phase
In the twelve months following the release, the industry has largely remained in a holding pattern. Many vendors opted for a wait-and-see approach, waiting for critical mass before allocating engineering resources to support 3.2.
- Q4 2025: Initial adoption began with core open-source libraries and parsers. Developers began experimenting with 3.2, but the lack of gateway support meant that few production-grade APIs could safely make the jump.
- Q1-Q2 2026: A period of "Partial Support" emerged. Vendors such as Postman and various SDK generators began updating their conversion logic. However, this period also birthed the "silent failure"—where tools would ingest 3.2 files but silently strip out features they didn’t recognize, such as the new
QUERYoperation types. - Q3 2026: The current state. We see a bifurcated market. A small group of proactive vendors (Scalar, Bump.sh, Mintlify, and others) have fully integrated 3.2, while the majority of the "legacy" enterprise ecosystem remains tethered to 3.0 or 3.1.
The Data: Version Support Across the Board
The disparity between reading and writing capabilities is the primary driver of the current ecosystem friction.
Who Reads What?
| Version | Hosted Vendors (45) | Open-Source Tools (48) | All (95) |
|---|---|---|---|
| Swagger 2.0 | 29 | 43 | 74 |
| OpenAPI 3.0 | 43 | 46 | 91 |
| OpenAPI 3.1 | 33 | 43 | 76 |
| OpenAPI 3.2 | 10 | 26 | 36 |
The data shows that Swagger 2.0—a specification now nearly a decade old—is still read by 74 tools. This "long tail" of support is a testament to the stability of older specifications but acts as an anchor on progress. If a developer can rely on 2.0 being universally read, the incentive to upgrade to 3.2 is dampened.
The Writing Problem
When it comes to the documents generated by server frameworks, the situation is even more critical.
- OpenAPI 3.0 remains the most common default.
- OpenAPI 3.1 has seen steady adoption in modern frameworks like FastAPI and Litestar.
- OpenAPI 3.2 is effectively invisible as a default.
With the exception of ASP.NET Core on .NET 11 and a few others, most developers have to manually flip a configuration switch to generate a 3.2 document. Because most developers stick with framework defaults, the "version of record" for most APIs remains years behind the cutting edge.
Implications: The Risks of "Partial" Support
Perhaps the most dangerous finding of this audit is the prevalence of "Partial Support." This is where a tool accepts a 3.2 document but quietly discards parts of it.
For instance, several code generators, including hey-api and orval, have been observed generating clients that completely omit new 3.2 operations. Similarly, documentation platforms like Redoc may build a page while simply ignoring 3.2-specific features.
This creates a "ghost in the machine" scenario. A developer publishes a 3.2 document, their CI/CD pipeline returns a "green" status, but the resulting documentation, SDK, or agent toolset is incomplete. Because there is no error message, the developer may never realize that their API consumers are missing critical functionality. This silent degradation of service is the primary reason why I recommend that providers currently stick to 3.1 for public-facing documentation.
The "Unknown" Category: Silence as a Strategy
Perhaps the most striking data point is the number of products that sit in the "Unknown" category—36 out of 56 hosted vendors. These platforms neither explicitly support nor reject 3.2; they simply exist in a state where the version has not yet been addressed.
Platforms like Apigee, Tyk, and WSO2, alongside major cloud gateways, have largely remained silent on 3.2. For these organizations, the priority is maintaining the status quo of 3.0 and 3.1 compatibility, which covers the vast majority of their customer base. While this makes business sense, it creates a "version wall" that prevents smaller, more innovative API designs from utilizing the full power of the latest specification.
The Path Forward: Where the Industry Must Pivot
The burden of solving this fragmentation does not lie with the API provider, but with the toolchain maintainers. If the community wants 3.2 to succeed, the work is narrow and specific:
- Parser Standardization: Two major libraries—
swagger-parserfor JavaScript and its Java counterpart—gate a massive portion of the open-source ecosystem. If these two parsers achieve full 3.2 compliance, the downstream impact would be immediate and profound. - Framework Defaults: Framework maintainers need to stop treating the latest version as an "experimental" flag. By shifting the default version emitted by frameworks like FastAPI, SpringDoc, and NestJS, we can force the ecosystem to prioritize 3.2 support.
- Vendor Documentation: Hosted vendors have a simple but effective task: explicitly state their version support. Moving a tool from "unknown" to "unsupported" is a victory for clarity, allowing developers to make informed choices about their architecture.
Conclusion: A Call for Pragmatism
The reality of the current API landscape is that we are in a state of transition. While OpenAPI 3.2 offers significant improvements in how we describe and manage modern APIs, the reality of the tooling ecosystem means that adoption must be handled with extreme caution.
For now, the safest path for any API provider is to continue publishing 3.1-compliant documents. Reserve 3.2 only for toolchains that have been explicitly vetted for full support. By resisting the urge to jump to the latest version until the ecosystem matures, developers can avoid the "silent failures" that are currently plaguing the industry.
We must remember that an API specification is only as good as the tools that process it. Until the parsers, generators, and gateways align, the "newest" version will remain a theoretical asset rather than a practical tool. The work ahead is not in writing better specifications, but in building the robust, transparent infrastructure that allows those specifications to thrive.
Lina Irawan
Sagoh
