Bagaimana saya bisa merepresentasikan 'Authorization: Bearer <token>' dalam Spesifikasi Swagger (swagger.json)

114

Saya mencoba menyampaikan bahwa skema otentikasi / keamanan memerlukan pengaturan tajuk sebagai berikut:

Authorization: Bearer <token>

Inilah yang saya miliki berdasarkan dokumentasi kesombongan :

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

Jawaban:

140

Mungkin ini bisa membantu:

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'

Anda dapat menyalin & menempelkannya di sini: http://editor.swagger.io/#/ untuk melihat hasilnya.

Ada juga beberapa contoh di web editor sombong dengan konfigurasi keamanan yang lebih kompleks yang dapat membantu Anda.

David Lopez
sumber
4
Saya tidak mengerti bagaimana Anda memberi tahu editor tentang pengguna dan kata sandi atau token Dasar yang harus dikirim sehingga Anda bisa mendapatkan 200. Apakah saya melewatkan sesuatu?
Rob
1
Baiklah jangan dipikirkan. Rupanya "Otentikasi" adalah sesuatu yang dapat Anda klik untuk mendapatkan formulir login.
Rob
Jadi, bagaimana cara menetapkan nilai ke token? saya mencoba curl -x get --header "Authorization: apiKey = 123" tetapi tidak ada yang terjadi
Gobliins
2
@Gobliins yang Anda inginkan curl -X GET -H "Authorization: Bearer your_token", di mana your_tokentoken pembawa Anda. Misalnyacurl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
Steve K
15
Sayangnya ini tidak berfungsi dengan baik dengan Swagger UI - mengklik "Otorisasi" dan memberikan token kosong akan menghasilkan contoh curl "Coba" dengan -H "Authorization: foo"alih - alih -H "Authorization: Bearer foo"menyukai jawaban OpenAPI 3
Abe Voelker
56

Otentikasi pembawa di OpenAPI 3.0.0

OpenAPI 3.0 sekarang mendukung otentikasi Bearer / JWT secara asli. Ini didefinisikan seperti ini:

openapi: 3.0.0
...

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

security:
  - bearerAuth: []

Ini didukung di Swagger UI 3.4.0+ dan Swagger Editor 3.1.12+ (sekali lagi, hanya untuk spesifikasi OpenAPI 3.0!).

UI akan menampilkan tombol "Otorisasi", yang dapat Anda klik dan masukkan token pembawa (cukup token itu sendiri, tanpa awalan "Pembawa"). Setelah itu, permintaan "try it out" akan dikirim dengan Authorization: Bearer xxxxxxheader.

Menambahkan Authorizationheader secara terprogram (Swagger UI 3.x)

Jika Anda menggunakan Swagger UI dan, karena alasan tertentu, perlu menambahkan Authorizationheader secara terprogram daripada meminta pengguna mengklik "Otorisasi" dan memasukkan token, Anda dapat menggunakan requestInterceptor. Solusi ini untuk Swagger UI 3.x ; UI 2.x menggunakan teknik yang berbeda.

// index.html

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

  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  }
})
Helen
sumber
1
Bagaimana cara mengimplementasikan ini dalam dokumentasi swagger yang dihasilkan flask-restplus?
Chang Zhao
Saya ragu apakah jawaban sesuai dengan pertanyaan yang ditanyakan.
Vishrant
16

Mengapa "Jawaban yang Diterima" berhasil ... tetapi itu tidak cukup bagi saya

Ini bekerja sesuai spesifikasi. Setidaknya swagger-tools(versi 0.10.1) memvalidasinya sebagai valid.

Tetapi jika Anda menggunakan alat lain seperti swagger-codegen(versi 2.1.6) Anda akan menemukan beberapa kesulitan, meskipun klien yang dibuat berisi definisi Otentikasi, seperti ini:

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

Tidak ada cara untuk meneruskan token ke header sebelum metode (titik akhir) dipanggil. Perhatikan tanda tangan fungsi ini:

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

Ini berarti bahwa, saya hanya meneruskan callback (dalam kasus lain parameter kueri, dll) tanpa token, yang mengarah ke pembuatan permintaan yang salah ke server.

Alternatif saya

Sayangnya, ini tidak "cantik" tetapi berfungsi sampai saya mendapatkan dukungan Token JWT di Swagger.

Catatan: yang sedang dibahas di

Jadi, ini menangani otentikasi seperti header standar. Pada pathobjek menambahkan paremeter header:

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'

Ini akan menghasilkan klien dengan parameter baru pada tanda tangan metode:

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

Untuk menggunakan metode ini dengan cara yang benar, cukup berikan "string lengkap"

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

Dan bekerja.

Paulo Oliveira
sumber
"Token berasal dari tempat lain" ... Saya tertarik di tempat lain. Bagaimana ketika Anda login diarahkan ke login Anda dan dialihkan ke api swagger Anda, bagaimana Anda bisa menggunakan token akses yang Anda terima?
Nadine
1

Memposting jawaban 2020 di JSON menggunakan openapi 3.0.0:

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


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

Cara Hackie saya untuk mengatasi ini adalah dengan memodifikasi file swagger.go dalam paket echo-swagger dalam kasus saya:

Di bagian bawah file, perbarui fungsi window.onload untuk menyertakan requestInterceptor yang memformat token dengan benar.

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

}

xXPhenom22Xx
sumber