如何在 OpenAPI 中使用 SEARCH 方法？

Question

有沒有人有處理 OpenAPI 中路徑操作的 AcceptVerb（例如“搜索”）的經驗？ 它會引發錯誤，因為“搜索”不是 Swagger Editor 接受的可接受的 HTTP 方法。

/dnlds/bwaaccount:
    summary: Searches for BOSS accounts
    description: >-
      Receives a BOSS search request and then the API will search the BOSS database.
    search:

這是我的 API 中的方法簽名：

[AcceptVerbs("SEARCH")]
public HttpResponseMessage Search()

Answer 1

從 v. 3.1 開始，OpenAPI 規范僅支持 GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS 和 TRACE 方法。 不支持搜索。

存在支持其他 HTTP 方法的現有功能請求，包括 SEARCH：

• 支持 SEARCH http 方法
• 支持所有 HTTP 方法

您可以更改實現以使用 GET 或 POST 而不是 SEARCH 嗎？

如果不是，一種將 SEARCH 方法定義為x-擴展的解決方法：

paths:
  /dnlds/bwaaccount:
    summary: Searches for BOSS accounts

    x-search:  # <-------
      summary: ...
      operationId: ...
      parameters: [...]
      responses:
        ...

如果您從代碼生成 OpenAPI 定義，則需要調整您的框架/庫以生成x-search而不是search 。

但是， x-擴展只是元數據，因此此解決方法實際上不會在基於 OpenAPI 的工具（例如 Swagger UI、OpenAPI Generator 等）中為您提供 SEARCH 支持。