PR #5253 - swagger-api/swagger-core

Adds support for the query HTTP method, which OpenAPI 3.2 introduced as a fixed field of the
Path Item Object,
and maps it from the JAX-RS annotation reader, while keeping it out of OpenAPI 3.0 and 3.1 output,
where the field is not valid.

Three commits, each self-contained:

swagger-models, PathItem.query: field, accessors and fluent builder, HttpMethod.QUERY,
and wiring through readOperations(), readOperationsMap(), operation(), equals, hashCode
and toString.
swagger-core, version gating: a new PathItemMixin marks getQuery() @JsonIgnore for the
3.0 and 3.1 mappers, so neither can emit a Path Item field that those versions do not define.
swagger-jaxrs2, Reader.setPathItemOperation routes "query" onto PathItem.query(), and
extractOperationIdFromPathItem includes query operationIds in the uniqueness check.

Motivation is swagger-parser's OpenAPI 3.2 work: the parser builds on swagger-models, so the model
has to be able to carry a query operation before 3.2 documents can be represented at all.

Refs: swagger-api/swagger-parser#2248

Type of Change

🐛 Bug fix
✨ New feature
♻️ Refactor (non-breaking change)
🧪 Tests
📝 Documentation
🧹 Chore (build or tooling)

Checklist

I have added/updated tests as needed
I have added/updated documentation where applicable
The PR title is descriptive
The code builds and passes tests locally
I have linked related issues (if any)

Screenshots / Additional Context

Three notes for reviewers

1. query is deliberately not emitted by any current mapper. swagger-core has no OpenAPI 3.2
support today , SpecVersion is V30/V31 only, so there is no mapper that may legitimately write
the field, and both existing ones are gated. The field is therefore enabling work for downstream
consumers rather than something that changes swagger-core's output. Adding SpecVersion.V32 plus
Json32/Yaml32 is the natural next step, but it is a much larger change (openapi31 is threaded as
a boolean through dozens of signatures across core, jaxrs2, integration and the build plugins), and
it commits the project to a 3.2 design that is better agreed up front than smuggled in here. Happy to
follow up on that in whatever shape you prefer.

2. The gating applies on read as well as write. @JsonIgnore on a mixin accessor removes the
property in both directions, so the 3.0/3.1 mappers also drop a query key when parsing. That is
symmetric with how SchemaMixin treats the 3.1-only schema fields ($id, $anchor, prefixItems, …)
under the 3.0 mapper, and it is pinned by an explicit test rather than left implicit.

3. No new public API in swagger-jaxrs2: the only main-source change there is the Reader switch
case. ReaderUtils.getHttpMethodFromCustomAnnotations already resolves any annotation meta-annotated
with @HttpMethod to its lower-cased method name, so an application's own @QUERY binding maps onto
PathItem.query with no further support needed. The @QUERY annotation in this PR lives in test
sources purely as the stand-in for that user-declared binding. If you would rather ship one from
swagger-jaxrs2 as a convenience, that is an easy addition, it just seemed like public surface you
should choose to own, not inherit from this PR.

Known follow-up

additionalOperations, the other new 3.2 Path Item field, is not included. It has its own design
questions like how non-enum methods surface through readOperations/readOperationsMap, and the spec
rule that the map MUST NOT duplicate methods with fixed fields, so it seemed better kept separate
than bundled here.

Test results

Full suites, run locally on JDK 21:

Module	Result
`swagger-models`	pass
`swagger-core`	749 tests, 0 failures
`swagger-jaxrs2`	227 tests, 0 failures

New coverage: PathItemTest (model wiring, equals/hashCode, readOperations*), two tests in
JsonSerializationTest (3.0 and 3.1 mappers omit query on write, drop it on read), and
QueryMethodTest (reader maps @QUERY onto PathItem.query; the resulting operation does not reach
Json/Json31/Yaml/Yaml31 output).