如何在 Swagger 规范中使用“授权：承载者 <token>”

Question

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

Authorization: Bearer <token>

这是我基于 swagger 文档：

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

Answer 1

也许这可以帮助：

swagger: '2.0'
info:
  version: 1.0.0
  title: Bearer auth example
  description: >
    An example for how to use Bearer Auth with OpenAPI / Swagger 2.0.

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

您可以将其复制并粘贴到https://editor.swagger.io查看结果。

Swagger Editor Web 中还有几个具有更复杂安全配置的示例可以帮助您。

重要提示： 在此示例中，API 使用者必须包含“Bearer”前缀作为令牌值的一部分。例如，当使用 Swagger UI 的“授权”对话框时，您需要输入

Bearer your_token

，而不仅仅是

your_token

。

Answer 2

OpenAPI 3.x 中的承载身份验证

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.x 规范！）。

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

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: "https://your.server.com/swagger.json",
  ...

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

Answer 3

使用 openapi 3.0.0 以 JSON 形式发布 2023 年答案：

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


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

Answer 4

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

这在规范中有效。至少

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 令牌支持。

注意：这正在

中讨论

• 安全性：添加对带有 Bearer 的授权标头的支持 身份验证方案#583
• 安全性的可扩展性 定义？第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);

并且有效。

Answer 5

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

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

Answer 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

}

Answer 7

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

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

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

*security={
     *{
     *"bearerAuth": {}},
     *},