Repository navigation
[Feature]: Support for OpenAPI Spec 3.2 #2248
Description
Feature Description
Add support for parsing and validating OpenAPI Specification 3.2.0. This update addresses the gap in current swagger-parser capabilities where only older OpenAPI versions are supported, preventing users from leveraging the latest specification features and improvements.
Use Case
- Modern API Development: Teams adopting OpenAPI 3.2.0 for new API specifications cannot use swagger-parser for validation, documentation generation, or code generation workflows
- Migration Projects: Organizations upgrading from older OpenAPI versions (3.0.x, 3.1.x) to 3.2.0 need tooling support to validate their migrated specifications
- CI/CD Pipelines: Automated API validation in deployment pipelines fails when encountering OpenAPI 3.2.0 specs, breaking development workflows
- Toolchain Integration: Downstream tools that rely on swagger-parser (documentation generators, mock servers, client SDK generators) cannot process 3.2.0 specs
Suggested Solution (optional)
- Schema Updates: Update the internal schema definitions to support OpenAPI 3.2.0 structure and validation rules
- Version Detection: Enhance version parsing to recognize
3.2.0in theopenapifield - Backward Compatibility: Maintain support for existing OpenAPI versions while adding 3.2.0 capabilities
- New Feature Support: Implement support for 3.2.0 specific features such as:
- Updated JSON Schema dialect (2020-12)
- New webhook object support
- Enhanced security scheme features
Alternatives Considered
Additional Context
- OpenAPI 3.2.0 Release Notes: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.2.0
- OpenAPI 3.2.0 Specification: https://spec.openapis.org/oas/v3.2.0
- Migration Guide: The 3.2.0 release is designed to be compatible with 3.1.0 with minimal breaking changes
- Industry Adoption: Growing number of API tools and platforms are adding 3.2.0 support
Checklist
- I have searched the existing issues to ensure this is not a duplicate.
- This feature would be useful to more than just my use case.
- I have provided enough detail for the maintainers to understand the scope of the request.
Activity
baywet commentedon Jan 12, 2026
To add some context here, I implemented 3.2.0 support twice recently:
While the design choices might be different here, this should give a good overview of the required changes. The only things that's missing in those two PRs is the implementation of dynamic reference resolution.
I hope this helps :)
beavuck commentedon Mar 14, 2026
Is this issue alive? I'm surprised it hasn't been acknowledged yet
EDIT: they are currently "working on OAS 3.2 support in editor", according to their recent community post #2284, and their ability to maintain swagger-parser has been "limited"
ayush-sharaf commentedon Jul 6, 2026
Adding a concrete downstream use case + repro to help gauge impact.
We're using TypeSpec → OpenAPI3 → openapi-generator (
typescript-axios) as our API pipeline. We want to adopt the HTTPQUERYmethod (RFC 10008), which OpenAPI 3.2.0 supports as a first-class path-item operation. We filed a feature request upstream for TypeSpec to emit it (microsoft/typespec#11171), but even once that lands, this repo is the blocking dependency for the whole chain — openapi-generator itself is blocked on this issue (OpenAPITools/openapi-generator#22728).Concretely, today:
"openapi": "3.2.0"— even with noqueryoperations at all — throws an NPE inside openapi-generator (7.14.0), because this parses tonull:"query"path-item operation on a3.1.0document is silently dropped (no operation emitted, no error) when generation is run with--skip-validate-spec— filed separately as [BUG] Unrecognized path-item operations (e.g. OpenAPI 3.2 'query') are silently dropped from generated code with --skip-validate-spec OpenAPITools/openapi-generator#24212, since the generator should surface this regardless of parser version support, but it's rooted in this parser not recognizing thequeryfield onPathItem.Happy to help test against a WIP branch if one exists — the reference implementations linked above (scalar's TS PR, OpenAPI.NET's PR) look like reasonable blueprints per @baywet's comment. Given swagger-core#5181 needs to land first for the
PathItem/Operationmodel changes, is there a preferred order of contribution (core first, then parser) if someone wanted to pick this up?CommanderGeek commentedon Jul 23, 2026
Hi, I'd like to help move this forward, starting with the new QUERY HTTP method from OAS 3.2 (the JS tooling shipped 3.2 support back in April, but the Java models/parser are still on 3.1).
I've had a look at where the gap is. On the swagger-core side,
PathItemhard-wires the eight 3.1 methods:so QUERY needs a new field + accessors, plus updates to
readOperations(),readOperationsMap(),operation(HttpMethod, Operation), andequals/hashCode/toString. On the swagger-parser side,OpenAPIDeserializerreads the path-item keys explicitly, so it needs"query"added there plus version detection for 3.2.x.I'd propose splitting this per repo rather than one big 3.2 change:
PathItem.query, version gating so 3.0/3.1 output stays valid, and the JAX-RS reader mapping (+ tests). Those land together because they are one Maven reactor: the reader callsPathItem.query()and the gating mixin referencesgetQuery(), so neither compiles without the model change.additionalOperationswould be a good separate follow-up.A potential implementation of the swagger-core half is at swagger-api/swagger-core#5253, happy to reshape it however you prefer, or to split it further if you would rather review the modules separately.
Two design questions, so I build the rest the way you want:
1. Version gating. As far as I can tell
@OpenAPI31is documentation-only and it has no@Retentionand nothing reads it, while the actual gating is done by the Jackson mixins (e.g.SchemaMixin@JsonIgnore-ing the 3.1-only fields for the 3.0 mapper). #5253 follows that pattern with aPathItemMixinthat hidesqueryfrom both the 3.0 and 3.1 mappers. Is that the mechanism you want for 3.2 constructs, and would you also like an@OpenAPI32marker alongside it for consistency with the 3.1 fields?That does mean nothing in swagger-core emits
queryyet, sinceSpecVersionisV30/V31today. I have assumed that addingSpecVersion.V32plusJson32/Yaml32is a separate and much larger piece of work it would touch theopenapi31boolean threaded through core, jaxrs2, integration and the build plugins but say if you would rather see it as part of this.2.
additionalOperations. Any preference on how it should eventually be modelled, so I do not design QUERY in a way that conflicts with it later? In particular, whether methods without fixed fields should surface throughreadOperations()/readOperationsMap()alongside the fixed-field ones.Thanks!
feat(jaxrs2): support OpenAPI 3.2 QUERY method in annotation reader
feat(jaxrs2): support OpenAPI 3.2 QUERY method in annotation reader
feat(jaxrs2): support OpenAPI 3.2 QUERY method in annotation reade
feat(jaxrs2): support OpenAPI 3.2 QUERY method in annotation reade
ca-stefan-cordes commentedon Sep 16, 2026
Looks like swagger-parser was "forgotten" in April 26 when announcing 3.2.0 support 🤔 ?
=> https://swagger.io/blog/swagger-launches-support-for-openapi-3-2-0/
khayashi4337 commentedon Sep 20, 2026
Opened #2401, which is a much narrower slice than what's being discussed here: it only
makes swagger-parser recognize
"openapi": "3.2.x"and route it through the existing3.1 code path (deserializer, resolver/dereferencer), so a 3.2 document no longer gets
rejected outright. It does not add support for any 3.2-only construct --
query,additionalOperations,$self,in: querystringparams, or$dynamicRef-- thosestill show up as "unexpected attribute" validation messages and aren't reproduced in
the parsed model.
@CommanderGeek's swagger-core work in swagger-api/swagger-core#5253 (the
PathItem.querymodel change) is the piece that actually needs to land first for any of those constructs
to be representable here at all -- this PR is meant to be a small, independent step that
doesn't conflict with or duplicate that effort, not an attempt to move ahead of it. Happy
to rebase/adjust once #5253's design questions are settled and a
SpecVersion.V32existsto replace the stopgap version-flag widening this PR uses in the meantime.
🤖 Generated with Claude Code
ceesvanegmond commentedon Oct 7, 2026
Hmmm... following this issue here. 3.2.0 still isn't supported by this library