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

未关闭 适合新手
#524 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 2 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
76/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
活跃
技术栈
java, kotlin, openapi, spring-boot, yaml
领域
backend, devtools

调研方向

从 SpringFrameworkAnnotations.kt 中的 MAPPING_ANNOTATIONS 开始,将现有的 HEAD/OPTIONS/TRACE 条目与 issue 中提出的 RequestMethod.QUERY mapping 进行比较;注意该查找也会在 import 收集期间运行,这就是 exclude: true 仍然失败的原因。添加该条目,然后运行处理器针对 Spring 注解的单元测试,并重新生成一个包含 query 操作的示例 spec,以确认 @RequestMapping(method = RequestMethod.QUERY) 的输出。完成意味着一个 query spec 能成功处理,并且未知的自定义方法会以清晰的消息失败,而不是抛出 NoSuchElementException。

由索引模型根据 Issue 内容生成。

描述

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.

主要语言
Kotlin
星标
56
派生
11
平均合并
4 天 10 小时
30 天内合并 PR
8

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

openapi-processor/openapi-processor-spring 的其他 Issue

查看 openapi-processor/openapi-processor-spring 的全部 Issue

相似的 Issue

更多 Kotlin Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。