ฉันจะแสดง 'Authorization: Bearer <token>' ใน Swagger Spec ได้อย่างไร (swagger.json)


117

ฉันพยายามจะสื่อว่ารูปแบบการตรวจสอบความถูกต้อง / ความปลอดภัยต้องการการตั้งค่าส่วนหัวดังนี้:

Authorization: Bearer <token>

นี่คือสิ่งที่ฉันมีตามเอกสารของ Swagger :

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

คำตอบ:


144

สิ่งนี้อาจช่วยได้:

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
โอเคไม่เป็นไร. เห็นได้ชัดว่า "Authenticate" คือสิ่งที่คุณสามารถคลิกเพื่อรับแบบฟอร์มเข้าสู่ระบบ
Rob

ฉันจะตั้งค่าให้กับโทเค็นได้อย่างไร? ฉันลอง curl -x get --header "Authorization: apiKey = 123" แต่ไม่มีอะไรเกิดขึ้น
Gobliins

2
@ ก๊อบลินที่คุณต้องการโทเค็นผู้ถือของคุณอยู่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"
Steve K

15
น่าเสียดายที่สิ่งนี้ใช้ไม่ได้กับ UI ของ Swagger - การคลิก "อนุญาต" และการให้โทเค็นเปล่าจะสร้างตัวอย่าง curl "ลองใช้" -H "Authorization: foo"แทน-H "Authorization: Bearer foo"คำตอบของ OpenAPI 3
Abe Voelker

57

การรับรองความถูกต้องของผู้ถือใน 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 จะแสดงปุ่ม "Authorize" ซึ่งคุณสามารถคลิกและป้อนโทเค็นของผู้ถือได้ (เฉพาะโทเค็นเท่านั้นโดยไม่มีคำนำหน้า "ผู้ถือ") หลังจากนั้นคำขอ "ทดลองใช้" จะถูกส่งไปพร้อมกับ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 ได้อย่างไร
Chang Zhao

ฉันสงสัยว่าคำตอบสอดคล้องกับคำถามที่ถามหรือไม่
Vishrant

16

ทำไม "คำตอบที่ยอมรับ" ได้ผล ... แต่มันไม่เพียงพอสำหรับฉัน

สิ่งนี้ใช้งานได้ในข้อกำหนด อย่างน้อยswagger-tools(เวอร์ชัน 0.10.1) ตรวจสอบว่าถูกต้อง

แต่ถ้าคุณใช้เครื่องมืออื่น ๆ เช่นswagger-codegen(เวอร์ชัน 2.1.6) คุณจะพบปัญหาแม้ว่าไคลเอ็นต์ที่สร้างขึ้นจะมีข้อกำหนดการรับรองความถูกต้องเช่นนี้:

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

ไม่มีวิธีส่งโทเค็นไปยังส่วนหัวก่อนที่จะเรียกวิธีการ (ปลายทาง) ดูลายเซ็นฟังก์ชันนี้:

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

ซึ่งหมายความว่าฉันส่งผ่านการเรียกกลับเท่านั้น (ในกรณีอื่น ๆ พารามิเตอร์การค้นหา ฯลฯ ) โดยไม่มีโทเค็นซึ่งนำไปสู่การสร้างคำขอไปยังเซิร์ฟเวอร์ที่ไม่ถูกต้อง

ทางเลือกของฉัน

น่าเสียดายที่มันไม่ "สวย" แต่ใช้งานได้จนกว่าฉันจะได้รับการสนับสนุน JWT Tokens บน Swagger

หมายเหตุ: ซึ่งกำลังกล่าวถึงใน

ดังนั้นจึงจัดการการตรวจสอบสิทธิ์เหมือนส่วนหัวมาตรฐาน บนpathวัตถุต่อท้าย paremeter ส่วนหัว:

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);

และใช้งานได้


"โทเค็นมาจากที่อื่น" ... ฉันสนใจที่อื่น จะเกิดอะไรขึ้นเมื่อคุณเข้าสู่ระบบและถูกเปลี่ยนเส้นทางไปยัง API ของคุณคุณจะใช้โทเค็นการเข้าถึงที่คุณได้รับได้อย่างไร
นาดีน

1

โพสต์คำตอบ 2020 ใน JSON โดยใช้ openapi 3.0.0:

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


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

0

วิธีแฮ็กกี้ของฉันในการแก้ปัญหานี้คือการแก้ไขไฟล์ swagger.go ในแพ็คเกจ echo-swagger ในกรณีของฉัน:

ที่ด้านล่างของไฟล์อัปเดตฟังก์ชัน 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

}

โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.