如何在 OpenAPI 3 中使用自定义前缀定义授权标头？

Posted 2023-02-19

【中文标题】如何在 OpenAPI 3 中使用自定义前缀定义授权标头？

【英文标题】：How to define the Authorization header with a custom prefix in OpenAPI 3?

【发布时间】：2021-11-26 19:39:18

【问题描述】：

我正在寻找正确的方法来指定具有自定义类型/前缀的 Authorization 标头，例如 OpenAPI 3 中的“ApiKey”。

自定义 Authorization 标头应如下所示

Authorization: ApiKey myAPIKeyHere

我所有使用type: apiKey 指定securitySchemes 条目的尝试似乎 产生其他结果...

我得到的最接近的是：

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: ApiKey

...但这会生成ApiKey: myAPIKeyHere 标头而不是Authorization: ApiKey myAPIKeyHere。

如何指定这样的要求？

【参考方案1】：

我想我找到了一种似乎可以接受的方法——尽管并不完美。想在未来看到更好的东西......

似乎除了将自定义类型添加到值之外别无他法（由下面的描述辅助）。

components:
  securitySchemes:
      ApiKey:
         type: apiKey
         name: Authorization
         in: header
         description: 'Prefix the value with \"ApiKey\" to indicate the custom authorization type' 
security:
   - ApiKey: []

这至少会在 curl 中生成正确的标题（如果应用正确的话）。

【讨论】：

这是正确答案。没有直接的方法可以为 Authorization 标头定义自定义前缀（即不同于 IANA-registered HTTP 身份验证方案的前缀）。解决方法是在描述字段中提及此自定义前缀，以便 API 使用者将此前缀作为标头值的一部分提供。

【参考方案2】：

请试试这个：

  securitySchemes:
    ApiKeyAuth:
       type: apiKey
       in: header
       name: ApiKey
  security
    - ApiKeyAuth: []

请查看文档：

-> 步骤 2. 应用安全性

Authentication and Authorization

【讨论】：

但这不会产生相同的结果吗？只是名称不同。我认为它仍然没有放在 Authorization 标头中......

@JoeFrizz。对不起。你说得对。我将编辑我的帖子

好吧，我现在可能错了，但是根据 swagger ui 编辑器，这会产生以下结果：pasteboard.co/IPtJnAO.png 有人怎么知道，必须使用自定义类型的 Authorization 标头？