Swagger/OpenAPI Bearer 身份验证与自定义标头名称

Question

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

我需要使用 Bearer auth 进行身份验证，但通过在Authorize.

服务器期望在一个X-Samanage-Authorization像这个例子一样命名的标头中进行承载身份验证：

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/，但它似乎并没有完全帮助我。

这（OpenAPI 3）

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

生成名为 default ( 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 Editor 中验证失败，因为我相信 a typeofhttp不允许name组件（就像一种apiKey会一样）。老实说，我无法完全理解这里的文档。

我确实读过规范扩展，但对 OpenAPI 来说是全新的，我找不到任何关于如何实际实现我需要的例子。

任何见解非常感谢！

Answer 1

type: http用于RFC 7235和IANA HTTP Authentication Scheme Registry定义的HTTP 身份验证。根据定义，HTTP 身份验证使用Authorization标头。

要使用自定义标头名称，您需要将其定义为API 密钥( type: apiKey)：

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

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