Swagger/OpenAPI 具有自定义 header 名称的承载身份验证

Question

我正在使用 OpenAPI 定义现有 API (Samanage) 的（小部分）以协助进行一些集成工作。

我需要使用 Bearer auth 进行身份验证，但是通过 header 而不是 Authorize 发送令牌。

服务器希望在名为 X-Samanage-Authorization 的 header 中进行 Bearer 身份验证，如下例所示：

curl -H "X-Samanage-Authorization: Bearer <TokenGoesHere>" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

我知道 https://swagger.io/docs/specification/authentication/bearer-authentication/，但它似乎并没有完全帮助我。

这个（打开API3）

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
...
security:
- bearerAuth: []

导致身份验证 header 命名为默认 (Authorization)

curl -X GET "https://api.samanage.com/incidents/12341234.json" -H "accept: application/json" -H "Authorization: Bearer <TokenGoesHere>"

然后失败 (401)。

我觉得我想要这个：

components:
  securitySchemes:
    bearerAuth:
      type: http
      name: X-Samanage-Authorization
      in: header
      scheme: bearer

但是在 Swagger 编辑器中验证失败，因为我相信 http 的 type 不允许 name 组件（就像 apiKey 的类型一样） .老实说，我无法完全理解文档 here。

我确实读过 Specification Extensions，但对 OpenAPI 完全陌生，我找不到任何关于如何实际实现我需要的示例。

非常感谢任何见解！

Answer 1

type: http 用于 RFC 7235 and the IANA HTTP Authentication Scheme Registry 定义的 HTTP 身份验证。根据定义，HTTP 身份验证使用 Authorization header.

要使用自定义 header 名称，您需要将其定义为 API key (type: apiKey):

components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      name: X-Samanage-Authorization
      in: header

请注意，由于它是 non-standard Bearer 方案，因此客户端需要手动将“Bearer”前缀添加到令牌值。例如，当您在 Swagger UI 中单击“授权”时，您需要输入“Bearer TOKEN”而不仅仅是“TOKEN”。

Swagger/OpenAPI 具有自定义 header 名称的承载身份验证

Swagger/OpenAPI Bearer auth with custom header name

authentication

swagger

openapi

swagger-editor