Как я могу представить "Authorization: Bearer" в спецификации Swagger (swagger.формат JSON)

Я пытаюсь передать, что схема аутентификации/безопасности требует установки заголовка следующим образом:

Authorization: Bearer <token>

это то, что я основал на документация swagger:

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

спасибо заранее!

61
swagger swagger-2.0 swagger-editor

3 ответов

может это поможет:

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 с более сложными конфигурациями безопасности, которые могут вам помочь.

81

аутентификация на предъявителя в OpenAPI 3.0.0

OpenAPI 3.0 теперь поддерживает аутентификацию носителя / 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 отобразит кнопку" авторизовать", которую вы можете нажать и ввести токен носителя (только сам токен, без префикса "носитель"). После этого запросы "попробовать" будут быть посланным с 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
  }
})
16

почему" принятый ответ " работает... но мне этого было мало!--10-->

это работает в спецификации. По крайней мере!--5--> (версия 0.10.1) проверяет, как действует.

а если вы используете другие инструменты, такие как swagger-codegen (версия 2.1.6) вы найдете некоторые трудности, даже если созданный клиент содержит определение аутентификации, например:

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

нет способа передать токен в заголовок до того, как метод (конечная точка) будет называемый. Посмотрите на эту сигнатуру функции:

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

это означает, что я только передаю обратный вызов (в других случаях параметры запроса и т. д.) без маркера, что приводит к неправильной сборке запроса на сервер.

Моя альтернатива

к сожалению, это не "красиво", но он работает, пока я не получу поддержку токенов JWT на Swagger.

Примечание: который обсуждается в

Итак, это аутентификация дескриптора как стандартный заголовок. On 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);

и работает.

12