带有自定义头名的Swagger/OpenAPI承载auth

Question

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

This（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>"

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

但这在Swagger编辑器中验证失败，因为我认为HTTP的类型不允许name组件（就像apikey类型一样）。老实说，我不能完全理解这里的医生。

我确实读过关于规范扩展的文章，但是我对OpenAPI是完全陌生的，我找不到任何关于如何实际实现我所需要的东西的例子。

任何洞察力都非常感谢！

Answer 1

类型:HTTP用于RFC7235和IANA HTTP authentication Scheme注册表定义的HTTP身份验证。根据定义，HTTP身份验证使用Authorization标头。

要使用自定义头名称，需要将其定义为API密钥(类型:apikey):

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

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