我如何在Swagger规范(swagger.json)中表示“授权:承载<令牌>”


Answers:


138

也许这可以帮助:

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编辑器网络中也有一些示例,它们具有更复杂的安全配置,可以为您提供帮助。


4
我看不到您如何告诉编辑者发送什么用户名和密码或基本令牌,因此您可以得到200。我是否缺少某些内容?
罗布

1
好的不要紧。显然,您可以单击“身份验证”以获取登录表单。
罗布

那么,如何为令牌设置值?我试过curl -x get --header“ Authorization:apiKey = 123”,但是什么都没发生
Gobliins

2
您想要的@Gobliins curl -X GET -H "Authorization: Bearer your_token"your_token承载令牌在哪里。EGcurl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
史蒂夫ķ

15
不幸的是,这不适用于Swagger UI-单击“授权”并提供裸令牌将生成“尝试一下” curl示例,-H "Authorization: foo"而不是-H "Authorization: Bearer foo"像OpenAPI 3那样回答
Abe Voelker

56

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将显示“授权”按钮,您可以单击该按钮并输入不记名令牌(仅令牌本身,不带“ 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: "http://your.server.com/swagger.json",
  ...

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

1
如何在flask-restplus生成的swagger文档中实现此目的?
Chang Zhao

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

16

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

这在规范中起作用。至少swagger-tools(版本0.10.1)将其验证为有效。

但是,如果您使用的是其他工具swagger-codegen(版本2.1.6),您将发现一些困难,即使生成的客户端包含Authentication定义,如下所示:

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

在调用method(endpoint)之前,无法将令牌传递到标头中。查看此函数签名:

this.rootGet = function(callback) { ... }

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

我的选择

不幸的是,它并不是“漂亮”的,但直到我在Swagger上获得JWT令牌支持后,它才起作用。

注意:正在讨论

因此,它像标准标头一样处理身份验证。在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);

和工程。


“令牌来自其他地方” ...我对其他地方感兴趣。当您登录时,直接登录并重定向到您的swagger api,怎么办?如何使用收到的访问令牌?
纳丁

0

使用openapi 3.0.0在JSON中发布2020年答案:

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


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

0

我的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

}

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.