Spring: support OpenAPI 3.2 `query` operations (HTTP QUERY, RFC 10008)

Open Beginner friendly
#524 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
java, kotlin, openapi, spring-boot, yaml
Domain
backend, devtools

Research direction

Start in SpringFrameworkAnnotations.kt at MAPPING_ANNOTATIONS and compare the existing HEAD/OPTIONS/TRACE entries with the RequestMethod.QUERY mapping proposed in the issue; note the lookup also runs during import collection, which is why exclude: true still fails. Add the entry, then run the processor's unit tests for the Spring annotations and regenerate a sample spec containing a query operation to confirm the @RequestMapping(method = RequestMethod.QUERY) output. Done means a query spec processes successfully and unknown custom methods fail with a clear message instead of a NoSuchElementException.

Written by the indexing model from the issue text.

Description

Description

openapi-processor-base 2025.6 added parser support for OpenAPI 3.2 query and custom
http methods (openapi-processor-base#313). However, openapi-processor-spring fails as soon
as the spec contains a query operation, because SpringFrameworkAnnotations has no
mapping annotation for HttpMethod.QUERY.

Spring Framework 7.1 (Spring Boot 4.2) now supports QUERY natively via
RequestMethod.QUERY / HttpMethod.QUERY, so the generated interface could use
@RequestMapping(method = RequestMethod.QUERY).

Versions
  • openapi-processor-spring: 2026.3.2 (latest release)
  • openapi-processor gradle plugin: 2026.2
  • Gradle 9.7.1, Java 25
Steps to reproduce

openapi/openapi.yaml:

openapi: 3.2.0
info:
  title: query sample
  version: 1.0.0
paths:
  /products:
    query:
      operationId: queryProducts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSearchCriteria'
      responses:
        '200':
          description: matching products
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
components:
  schemas:
    ProductSearchCriteria:
      type: object
      properties:
        keyword:
          type: string

openapi/mapping.yaml:

openapi-processor-mapping: v17
options:
  package-name: com.example.api

Run ./gradlew processSpring.

Actual result
processing failed!
java.util.NoSuchElementException: Key QUERY is missing in the map.
    at io.openapiprocessor.spring.processor.SpringFrameworkAnnotations.getAnnotation(SpringFrameworkAnnotations.kt:32)
    at io.openapiprocessor.core.writer.java.InterfaceWriter.collectImports(InterfaceWriter.kt:59)
    at io.openapiprocessor.core.writer.java.InterfaceWriter.write(InterfaceWriter.kt:33)
    at io.openapiprocessor.core.writer.java.ApiWriter.writeInterface(ApiWriter.kt:114)
    ...

Excluding the endpoint in mapping.yaml gives the same error:

map:
  paths:
    /products:
      query:
        exclude: true

Changing only query: to post: in the same spec generates code successfully:

@PostMapping(path = "/products", consumes = {"application/json"}, produces = {"application/json"})
String[] queryProducts(@RequestBody ProductSearchCriteria body);

As a result, a spec that contains any query operation cannot be processed at all.

Expected result

Something like the following, analogous to how HEAD/OPTIONS/TRACE are generated today:

@RequestMapping(path = "/products", method = RequestMethod.QUERY, consumes = {"application/json"}, produces = {"application/json"})
String[] queryProducts(@RequestBody ProductSearchCriteria body);
Possible fix

Add an entry to MAPPING_ANNOTATIONS in SpringFrameworkAnnotations.kt:

HttpMethod.QUERY to Annotation(getMappingAnnotationName("request"), linkedMapOf(
    "method" to SimpleParameterValue("RequestMethod.QUERY", ANNOTATION_REQUEST_METHOD))
),

Notes:

  • RequestMethod.QUERY exists only in Spring Framework 7.1+. Generated code for a spec
    with query operations would therefore require Spring 7.1. This seems acceptable, since
    such a spec cannot be implemented on older Spring versions anyway, but it may be worth
    documenting.
  • Custom methods from additionalOperations (e.g. COPY) cannot be expressed with Spring's
    RequestMethod enum. A clear error message (or skipping them with a warning) would be
    better than a NoSuchElementException.
  • Spring 7.1 does not (yet) provide a @QueryMapping shortcut annotation, so
    @RequestMapping(method = RequestMethod.QUERY) is the way to declare it.

I verified on Spring Boot 4.2.0 with embedded Tomcat 11 that a hand-written controller
using @RequestMapping(method = RequestMethod.QUERY) works, including JSON and form-urlencoded
request bodies. The generated interface should work the same way.

Dominant language
Kotlin
Stars
56
Forks
11
Avg merge
4d 10h
Merged PRs (30d)
8

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openapi-processor/openapi-processor-spring

All issues in openapi-processor/openapi-processor-spring

Similar issues

More Kotlin issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.