OpenAPI 3.2 model support: SpecVersion.V32 platform + $self/Parameter/additionalOperations/MediaType fields

Draft
KH
2mo ago
+4030-215

Status: Draft — blocked on #5253, #5254, #5255

This PR is not ready to merge. It is built directly on top of three other
open, unreviewed PRs from other contributors, none of which have landed yet:

  • #5253 (@CommanderGeek) — adds PathItem.query (the OAS 3.2 QUERY HTTP
    method) and JAX-RS reader support. This branch is forked from that PR's
    branch, so its three commits appear first in this diff.
  • #5255 (@Mattias-Sehlstedt) — refactors ObjectMapperFactory to use the
    SpecVersion enum, in preparation for 3.2. Cherry-picked into this branch
    (commit afca0dec9), author preserved.
  • #5254 (@Mattias-Sehlstedt) — companion test refactor for the above.
    Cherry-picked (commit 7ff73a880), author preserved.

I opened this as a draft so the remaining OAS 3.2 model work is visible and
reviewable in context, without implying it's ready to merge ahead of the PRs
it depends on. Once #5253/#5254/#5255 land (in whatever form the maintainers
prefer), I'll rebase this on top of the merged result and drop the
now-duplicate commits.

What this adds (on top of #5253/#5254/#5255)

Working toward full OpenAPI 3.2 model support (tracked in #2248):

  • SpecVersion.V32 and a 3.2 Jackson mapper/gating platform (Json32/
    Yaml32), following the existing 3.0/3.1 mixin pattern. Wires up
    PathItem.query (from #5253) so it's actually serialized for 3.2 documents
    instead of being unconditionally hidden.
  • OpenAPI.$self (root document canonical-URI field)
  • Parameter 3.2 additions: in: querystring (new QueryStringParameter
    type) and style: cookie
  • MediaType/Encoding nested encoding: prefixEncoding, itemEncoding
  • PathItem.additionalOperations (arbitrary-named operations beyond the 8
    fixed HTTP methods), following the minimal-addition option from a design
    memo evaluated separately (kept fixed fields, added a side map — avoids an
    API/serializer redesign that would diverge further from #5253's approach)
  • MediaType.$ref (Reference Object semantics) + Components.mediaTypes
  • Simpler fixed-field additions: Server.name, Tag.summary/parent/kind,
    ApiResponse.summary, Example.dataValue/serializedValue,
    SecurityScheme.deprecated/oauth2MetadataUrl, OAuth device-flow fields,
    XML.nodeType, Discriminator.defaultMapping

Known limitations (disclosed, not blocking this draft)

  • The openapi31 boolean's meaning is widened to "3.1-family or later" as a
    stopgap; once SpecVersion gains more structure upstream this should be
    revisited.
  • 3.2 output is currently only reachable by calling Json32/Yaml32
    directly — SwaggerConfiguration, the jaxrs2 SwaggerSerializers, and the
    Maven/Gradle plugins don't yet select the 3.2 mapper. Wiring that up is a
    separate, larger change.
  • A handful of generators/consumers that call PathItem.readOperationsMap()
    directly (bypassing higher-level traversal) will now also see QUERY as a
    legitimate enum value, which is a natural consequence of #5253 rather than
    something this PR introduces.

Testing

Full reactor mvn clean install: 21 modules, all green. swagger-core
module 842 tests, swagger-jaxrs2 module 232 tests, 0 failures. New coverage
added across OpenAPI3_2SerializationTest, ValidationAnnotationsUtilsTest,
and QueryMethodTest.

🤖 Generated with Claude Code