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 摘要。