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

Aberta Para iniciantes
#524 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 2 dias

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
76/100
Tipo de issue
Funcionalidade
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
java, kotlin, openapi, spring-boot, yaml
Domínio
backend, devtools

Direção de pesquisa

Comece em SpringFrameworkAnnotations.kt em MAPPING_ANNOTATIONS e compare as entradas HEAD/OPTIONS/TRACE existentes com o mapping RequestMethod.QUERY proposto na issue; observe que a lookup também é executada durante a coleta de imports, por isso exclude: true ainda falha. Adicione a entrada, depois execute os testes unitários do processador para as anotações Spring e regenere uma spec de exemplo contendo uma operação query para confirmar a saída de @RequestMapping(method = RequestMethod.QUERY). Concluído significa que uma spec query é processada com sucesso e que métodos personalizados desconhecidos falham com uma mensagem clara em vez de uma NoSuchElementException.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Kotlin
Estrelas
56
Forks
11
Merge médio
4d 10h
PRs com merge (30d)
8

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de openapi-processor/openapi-processor-spring

Todas as issues de openapi-processor/openapi-processor-spring

Issues semelhantes

Mais issues de Kotlin

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.