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

Aperta Adatta ai principianti
#524 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
76/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
java, kotlin, openapi, spring-boot, yaml
Ambito
backend, devtools

Direzione di ricerca

Inizia in SpringFrameworkAnnotations.kt a MAPPING_ANNOTATIONS e confronta le voci esistenti HEAD/OPTIONS/TRACE con il mapping RequestMethod.QUERY proposto nell'issue; nota che la lookup viene eseguita anche durante la raccolta degli import, motivo per cui exclude: true fallisce ancora. Aggiungi la voce, poi esegui gli unit test del processore per le annotazioni Spring e rigenera una spec di esempio contenente un'operazione query per confermare l'output di @RequestMapping(method = RequestMethod.QUERY). Fatto significa che una spec query viene elaborata correttamente e che i metodi personalizzati sconosciuti falliscono con un messaggio chiaro invece che con una NoSuchElementException.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Kotlin
Stelle
56
Fork
11
Merge medio
4g 10h
PR unite (30g)
8

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openapi-processor/openapi-processor-spring

Tutte le issue di openapi-processor/openapi-processor-spring

Issue simili

Altre issue su Kotlin

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.