Jak mogę przedstawić „Authorization: Bearer <token>” w specyfikacji Swagger (swagger.json)

114

Próbuję przekazać, że schemat uwierzytelniania / bezpieczeństwa wymaga ustawienia nagłówka w następujący sposób:

Authorization: Bearer <token>

Oto, co mam na podstawie dokumentacji swagger :

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []
Elmer Thomas
źródło

Odpowiedzi:

140

Może to pomoże:

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'

Możesz go skopiować i wkleić tutaj: http://editor.swagger.io/#/ aby sprawdzić wyniki.

Istnieje również kilka przykładów w Internecie edytora swagger z bardziej złożonymi konfiguracjami zabezpieczeń, które mogą ci pomóc.

David Lopez
źródło
4
Nie rozumiem, jak możesz powiedzieć redaktorowi, jakiego użytkownika i hasła lub token podstawowego wysłać, aby otrzymać 200. Czy coś mi brakuje?
Rob
1
Ok nieważne. Najwyraźniej „Uwierzytelnij” to coś, na co możesz kliknąć, aby uzyskać formularz logowania.
Rob,
Jak więc ustawić wartość tokenu? Próbowałem curl -x get --header "Autoryzacja: apiKey = 123", ale nic się nie stało
Gobliins
2
@Gobliins chcesz curl -X GET -H "Authorization: Bearer your_token", gdzie your_tokenjest twój token okaziciela. Np.curl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
Steve K
15
Niestety nie działa to dobrze z interfejsem Swagger UI - kliknięcie „Autoryzuj” i podanie gołego tokena spowoduje wygenerowanie przykładów curl „Wypróbuj” -H "Authorization: foo"zamiast -H "Authorization: Bearer foo"odpowiedzi OpenAPI 3
Abe Voelker
56

Uwierzytelnianie okaziciela w OpenAPI 3.0.0

OpenAPI 3.0 obsługuje teraz natywnie uwierzytelnianie Bearer / JWT. Jest zdefiniowany w ten sposób:

openapi: 3.0.0
...

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

security:
  - bearerAuth: []

Jest to obsługiwane w Swagger UI 3.4.0+ i Swagger Editor 3.1.12+ (ponownie, tylko dla specyfikacji OpenAPI 3.0!).

Interfejs użytkownika wyświetli przycisk „Autoryzuj”, który można kliknąć i wprowadzić token okaziciela (sam token, bez prefiksu „Okaziciela”). Następnie żądania „wypróbuj” będą wysyłane z rozszerzeniemAuthorization: Bearer xxxxxx nagłówkiem.

AuthorizationProgramowe dodawanie nagłówka (Swagger UI 3.x)

Jeśli korzystasz z interfejsu użytkownika Swaggera i z jakiegoś powodu potrzebujesz Authorizationprogramowo dodać nagłówek, zamiast zmuszać użytkowników do klikania „Autoryzuj” i wprowadzania tokenu, możesz użyć rozszerzenia requestInterceptor. To rozwiązanie jest przeznaczone dla interfejsu Swagger UI 3.x ; W interfejsie użytkownika 2.x zastosowano inną technikę.

// index.html

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

  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  }
})
Helen
źródło
1
Jak zaimplementować to w dokumentacji generowanej przez flask-restplus?
Chang Zhao,
Wątpię, czy odpowiedź zgadza się z zadanym pytaniem.
Vishrant
16

Dlaczego „Accepted Answer” działa… ale to mi nie wystarczało

Działa to w specyfikacji. Przynajmniej swagger-tools(wersja 0.10.1) sprawdza, czy jest on prawidłowy.

Ale jeśli używasz innych narzędzi, takich jak swagger-codegen(wersja 2.1.6), napotkasz pewne trudności, nawet jeśli wygenerowany klient zawiera definicję uwierzytelniania, taką jak ta:

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

Nie ma możliwości przekazania tokenu do nagłówka przed wywołaniem metody (punktu końcowego). Spójrz na ten podpis funkcji:

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

Oznacza to, że przekazuję tylko wywołanie zwrotne (w innych przypadkach parametry zapytania itp.) Bez tokena, co prowadzi do nieprawidłowej kompilacji żądania do serwera.

Moja alternatywa

Niestety nie jest „ładna”, ale działa, dopóki nie otrzymam wsparcia JWT Tokens na Swagger.

Uwaga: która jest omawiana w

Tak więc uwierzytelnianie uchwytu jest takie jak standardowy nagłówek. Do pathobiektu dołącz parametr nagłówka:

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'

Spowoduje to wygenerowanie klienta z nowym parametrem w sygnaturze metody:

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

Aby użyć tej metody we właściwy sposób, po prostu podaj „pełny ciąg”

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

I działa.

Paulo Oliveira
źródło
„token pochodzi skądinąd”… Interesuje mnie gdzie indziej. Co kiedy się zalogowałeś, zostałeś przekierowany do twojego loginu i przekierowany do twojego Swagger API, jak możesz wykorzystać otrzymany token dostępu?
Nadine
1

Publikowanie odpowiedzi 2020 w formacie JSON przy użyciu 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
źródło
0

Mój sposób Hackie na rozwiązanie tego problemu polegał na zmodyfikowaniu pliku swagger.go w pakiecie echo-swagger w moim przypadku:

U dołu pliku zaktualizuj funkcję window.onload tak, aby zawierała requestInterceptor, który poprawnie formatuje token.

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
źródło