Bind remaining OpenAPI 3.2 fields (query/additionalOperations/$self/querystring/mediaTypes) and validate them

Draft
KH
2mo ago
+1748-72

Status: Draft — blocked on swagger-core releasing OAS 3.2 model support

This PR is not ready to merge. It builds on #2401 (already open, please
review that one first — it only makes swagger-parser accept "openapi": "3.2.x" and route it through the 3.1 code path, without populating any
3.2-only fields), and depends on model changes that only exist in a fork of
swagger-core (swagger-api/swagger-core#5326, itself a draft blocked on
#5253/#5254/#5255). pom.xml currently points at a locally-installed
2.2.56-SNAPSHOT that isn't available to anyone else — this PR cannot build
or pass CI until that lands upstream.

I opened it as a draft anyway so the parsing/validation work is visible and
reviewable in context, rather than sitting unpublished. I'll drop the
dependency on the fork and rebase once swagger-core cuts a release with the
3.2 model support.

What this adds (on top of #2401)

Actually reads the OAS 3.2-only fields into the parsed model, instead of
just tolerating the "3.2" version string:

  • PathItem.query, PathItem.additionalOperations, root $self,
    Parameter in: querystring (+ style: cookie), Components.mediaTypes,
    MediaType.$ref/itemSchema/prefixEncoding/itemEncoding, nested
    Encoding, and the simpler 3.2 fields (Server.name, Tag.*,
    Example.dataValue/serializedValue, etc.)
  • Reference resolution: the 3.1-family traversers/dereferencers now walk
    into all of the above (forward $id references, nested $refs inside
    additionalOperations/query/mediaTypes/encoding all resolve)
  • Semantic validation: in: querystring requires content and forbids
    schema/style/explode/allowReserved/allowEmptyValue; it can't
    coexist with in: query for the same effective parameter (checked within
    a parameter list, across path-item/operation level with correct override
    semantics, and through $ref to components.parameters); duplicate
    additionalOperations keys against the 8 fixed methods are flagged
    case-insensitively, matching the OAS 3.2 spec's own example
    (POST vs. fixed field post)

Known limitations (disclosed, not blocking this draft)

  • $self is bound as a field but not yet used as the base URI for reference
    resolution (OAS 3.2 gives it that role) — deferred.
  • A $ref to a parameter in an external document isn't checked for the
    query/querystring conflict (external refs aren't resolved at
    deserialize time) — disclosed as a known gap, not silently mishandled.
  • Referencing a boolean-valued schema (e.g. itemSchema: false via $ref)
    hits a pre-existing resolver defect (a BooleanNode→ObjectNode cast)
    that this PR's new code paths expose but did not introduce.

Testing

Full reactor mvn install: 7 modules, all green. swagger-parser-v3 module
759 tests (733 TestNG + 26 separately-run JUnit classes), 0 failures.
OAI32DeserializationTest alone: 37 cases covering parsing, round-trips,
reference resolution, and the validation rules above.

🤖 Generated with Claude Code