如何在 Swagger Spec (swagger.json) 中表示“授权：承载 <token>”

Posted 2023-02-16

【中文标题】如何在 Swagger Spec (swagger.json) 中表示“授权：承载 <token>”

【英文标题】：How can I represent 'Authorization: Bearer <token>' in a Swagger Spec (swagger.json)

【发布时间】：2015-12-30 20:02:19

【问题描述】：

我试图传达身份验证/安全方案需要设置如下标头：

Authorization: Bearer <token>

这是我基于swagger documentation的内容：

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []

【参考方案1】：

也许这会有所帮助：

swagger: '2.0'
info:
  version: 1.0.0
  title: Based on "Basic Auth Example"
  description: >
    An example for how to use Auth with Swagger.

host: basic-auth-server.herokuapp.com
schemes:
  - http
  - https
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
paths:
  /:
    get:
      security:
        - Bearer: []
      responses:
        '200':
          description: 'Will send `Authenticated`'
        '403': 
          description: 'You do not have necessary permissions for the resource'

您可以在此处复制并粘贴它：http://editor.swagger.io/#/ 以查看结果。

swagger 编辑器网页中还有几个示例，它们具有更复杂的安全配置，可以帮助您。

【讨论】：

我不明白您是如何告诉编辑器要发送什么用户和密码或基本令牌以便您获得 200。我错过了什么吗？

好吧，没关系。显然，“身份验证”是您可以单击以获取登录表单的内容。

@Gobliins 你想要curl -X GET -H "Authorization: Bearer your_token"，其中your_token 是你的不记名令牌。例如。 curl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"

不幸的是，这不适用于 Swagger UI - 单击“授权”并提供一个裸令牌将生成带有 -H "Authorization: foo" 而不是 -H "Authorization: Bearer foo" 的“试用” curl 示例，如 OpenAPI 3回答

我的解决方法是将 Bearer xxxxxxxx 作为 UI 授权框中的密钥。这行得通，但缺点是告诉用户手动输入 Bearer，然后输入密钥。或者，您可以修改返回 API 密钥的函数/方法，以将 Bearer 前缀作为密钥的一部分。

【参考方案2】：

OpenAPI 3.0.0 中的承载认证

OpenAPI 3.0 现在原生支持 Bearer/JWT 身份验证。它是这样定义的：

openapi: 3.0.0
...

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # optional, for documentation purposes only

security:
  - bearerAuth: []

这在 Swagger UI 3.4.0+ 和 Swagger Editor 3.1.12+ 中受支持（同样，仅适用于 OpenAPI 3.0 规范！）。

UI 将显示“授权”按钮，您可以单击该按钮并输入不记名令牌（只是令牌本身，没有“不记名”前缀）。之后，“试用”请求将使用Authorization: Bearer xxxxxx 标头发送。

以编程方式添加 Authorization 标头（Swagger UI 3.x）

如果您使用 Swagger UI，并且由于某种原因需要以编程方式添加 Authorization 标头，而不是让用户单击“授权”并输入令牌，则可以使用 requestInterceptor。此解决方案适用于 Swagger UI 3.x； UI 2.x 使用了不同的技术。

// index.html

const ui = SwaggerUIBundle(
  url: "http://your.server.com/swagger.json",
  ...

  requestInterceptor: (req) => 
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  
)

【讨论】：

如何在 flask-restplus 生成的 swagger 文档中实现这一点？

我怀疑答案是否与提出的问题一致。

通过这样做我得到没有路线匹配错误

【参考方案3】：

为什么“接受的答案”有效...但对我来说还不够

这在规范中有效。至少 swagger-tools（版本 0.10.1）将其验证为有效。

但是如果您使用其他工具，例如swagger-codegen（2.1.6 版），您会发现一些困难，即使生成的客户端包含身份验证定义，如下所示：

this.authentications = 
  'Bearer': type: 'apiKey', 'in': 'header', name: 'Authorization'
;

在调用方法（端点）之前，无法将令牌传递到标头中。查看此函数签名：

this.rootGet = function(callback)  ... 

这意味着，我只传递没有令牌的回调（在其他情况下是查询参数等），这会导致对服务器的请求构建不正确。

我的选择

不幸的是，它并不“漂亮”，但在我在 Swagger 上获得 JWT 令牌支持之前它一直有效。

注意：这是在讨论

security: add support for Authorization header with Bearer authentication scheme #583 Extensibility of security definitions? #460

因此，它像标准标头一样处理身份验证。在path 对象上附加一个标头参数：

swagger: '2.0'
info:
  version: 1.0.0
  title: Based on "Basic Auth Example"
  description: >
    An example for how to use Auth with Swagger.

host: localhost
schemes:
  - http
  - https
paths:
  /:
    get:
      parameters:
        - 
          name: authorization
          in: header
          type: string
          required: true
      responses:
        '200':
          description: 'Will send `Authenticated`'
        '403': 
          description: 'You do not have necessary permissions for the resource'

这将在方法签名上生成一个带有新参数的客户端：

this.rootGet = function(authorization, callback) 
  // ...
  var headerParams = 
    'authorization': authorization
  ;
  // ...

要正确使用此方法，只需传递“完整字符串”

// 'token' and 'cb' comes from elsewhere
var header = 'Bearer ' + token;
sdk.rootGet(header, cb);

并且有效。

【讨论】：

"token 来自其他地方"...我对其他地方感兴趣。当您登录时被定向到您的登录名并重定向到您的 swagger api，您如何使用您收到的访问令牌？

【参考方案4】：

使用 openapi 3.0.0 以 JSON 格式发布 2021 年答案：

  "openapi": "3.0.0",
  ...
  "servers": [
    
      "url": "/"
    
  ],
  ...
  "paths": 
    "/skills": 
      "put": 
        "security": [
           
              "bearerAuth": []
           
        ],
       ...
  ,


  "components":         
    "securitySchemes": 
      "bearerAuth": 
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      
    
  

【讨论】：

工作就像一个魅力:-))

【参考方案5】：

通过使用 requestInterceptor，它对我有用：

const ui = SwaggerUIBundle(
  ...
  requestInterceptor: (req) => 
    req.headers.Authorization = "Bearer " + req.headers.Authorization;
    return req;
  ,
  ...
);

【参考方案6】：

我的 Hackie 解决这个问题的方法是修改 echo-swagger 包中的 swagger.go 文件：

在文件的底部更新 window.onload 函数以包含一个正确格式化令牌的 requestInterceptor。

window.onload = function() 
  // Build a system
  const ui = SwaggerUIBundle(
  url: ".URL",
  dom_id: '#swagger-ui',
  validatorUrl: null,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ,
  layout: "StandaloneLayout",
  requestInterceptor: (req) => 
    req.headers.Authorization = "Bearer " + req.headers.Authorization
  return req
  
)

window.ui = ui

【参考方案7】：

从 laravel 7x ("openapi": "3.0.0") 解决这个问题，使用以下代码编辑您的 config\l5-swagger.php

'securityDefinitions' => [
                'securitySchemes' => [
                    'bearerAuth' => [ 
                        'type' => 'http',
                        'scheme' => 'bearer',
                        'bearerFormat' => 'JWT', 
                    ], 
                ],

然后您可以将其添加为端点的安全注释：

*security=
     *
     *"bearerAuth": ,
     *,