Wie kann ich 'Authorization: Bearer <token>' in einer Swagger Spec (swagger.json) darstellen?

112

Ich versuche zu vermitteln, dass für das Authentifizierungs- / Sicherheitsschema ein Header wie folgt festgelegt werden muss:

Authorization: Bearer <token>

Dies ist, was ich basierend auf der Prahler-Dokumentation habe :

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

Antworten:

137

Vielleicht kann das helfen:

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'

Sie können es hier kopieren und einfügen: http://editor.swagger.io/#/ , um die Ergebnisse zu überprüfen.

Es gibt auch einige Beispiele im Swagger Editor-Web mit komplexeren Sicherheitskonfigurationen, die Ihnen helfen könnten.

David Lopez
quelle
4
Ich verstehe nicht, wie Sie dem Editor mitteilen, welchen Benutzer und welches Kennwort oder welches Basic-Token gesendet werden sollen, damit Sie eine 200 erhalten können. Vermisse ich etwas?
Rob
1
Ok, vergiss 'es. Anscheinend können Sie auf "Authentifizieren" klicken, um ein Anmeldeformular zu erhalten.
Rob
Wie setze ich einen Wert für das Token? Ich habe versucht, Curl -x zu bekommen --header "Authorization: apiKey = 123", aber nichts ist passiert
Gobliins
2
@Gobliins du willst curl -X GET -H "Authorization: Bearer your_token", wo your_tokenist dein Inhaber Token. ZBcurl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
Steve K
14
Leider funktioniert dies nicht gut mit der Swagger-Benutzeroberfläche. Wenn Sie auf "Autorisieren" klicken und ein nacktes Token bereitstellen, werden Curl-Beispiele zum Ausprobieren generiert, -H "Authorization: foo"anstatt -H "Authorization: Bearer foo"wie bei der OpenAPI 3-Antwort
Abe Voelker,
56

Trägerauthentifizierung in OpenAPI 3.0.0

OpenAPI 3.0 unterstützt jetzt die Bearer / JWT-Authentifizierung nativ. Es ist so definiert:

openapi: 3.0.0
...

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

security:
  - bearerAuth: []

Dies wird in Swagger UI 3.4.0+ und Swagger Editor 3.1.12+ unterstützt (wiederum nur für OpenAPI 3.0-Spezifikationen!).

Auf der Benutzeroberfläche wird die Schaltfläche "Autorisieren" angezeigt, auf die Sie klicken und das Inhaber-Token eingeben können (nur das Token selbst ohne das Präfix "Träger"). Danach werden "Try it out" -Anfragen mit dem Authorization: Bearer xxxxxxHeader gesendet .

AuthorizationProgrammgesteuertes Hinzufügen von Headern (Swagger UI 3.x)

Wenn Sie die Swagger-Benutzeroberfläche verwenden und aus irgendeinem Grund den AuthorizationHeader programmgesteuert hinzufügen müssen, anstatt dass die Benutzer auf "Autorisieren" klicken und das Token eingeben, können Sie das verwenden requestInterceptor. Diese Lösung ist für Swagger UI 3.x ; UI 2.x verwendete eine andere Technik.

// index.html

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

  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  }
})
Helen
quelle
1
Wie implementiere ich dies in einer von Flask-Restplus generierten Swagger-Dokumentation?
Chang Zhao
Ich bezweifle, dass die Antwort mit der gestellten Frage übereinstimmt.
Vishrant
16

Warum "Akzeptierte Antwort" funktioniert ... aber es hat mir nicht gereicht

Dies funktioniert in der Spezifikation. Zumindest swagger-tools(Version 0.10.1) validiert es als gültig.

Wenn Sie jedoch andere Tools wie swagger-codegen(Version 2.1.6) verwenden, treten einige Schwierigkeiten auf, selbst wenn der generierte Client die folgende Authentifizierungsdefinition enthält:

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

Es gibt keine Möglichkeit, das Token an den Header zu übergeben, bevor die Methode (Endpunkt) aufgerufen wird. Schauen Sie sich diese Funktionssignatur an:

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

Dies bedeutet, dass ich den Rückruf (in anderen Fällen Abfrageparameter usw.) nur ohne Token weitergebe, was zu einem falschen Build der Anforderung an den Server führt.

Meine Alternative

Leider ist es nicht "hübsch", aber es funktioniert, bis ich Unterstützung für JWT-Tokens auf Swagger bekomme.

Hinweis: Dies wird in diskutiert

Die Authentifizierung wird also wie ein Standardheader behandelt. pathFügen Sie am Objekt einen Header-Parameter hinzu:

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'

Dadurch wird ein Client mit einem neuen Parameter für die Methodensignatur generiert:

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

Um diese Methode richtig anzuwenden, übergeben Sie einfach die "vollständige Zeichenfolge".

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

Und funktioniert.

Paulo Oliveira
quelle
"Token kommt von woanders" ... Ich interessiere mich für das Woanders. Was, wenn Sie sich angemeldet haben, wurde zu Ihrem Login geleitet und zu Ihrer Prahler-API umgeleitet? Wie können Sie das erhaltene Zugriffstoken verwenden?
Nadine
0

Antwort 2020 in JSON mit openapi 3.0.0 veröffentlichen:

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


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

Mein Hackie-Weg, um dies zu lösen, bestand darin, die Datei swagger.go im Paket echo-swagger in meinem Fall zu ändern:

Aktualisieren Sie am Ende der Datei die Funktion window.onload, um einen requestInterceptor einzuschließen, der das Token korrekt formatiert.

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
quelle