Как я могу представить 'Authorization: Bearer <token>' в спецификации Swagger (swagger.json)


114

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

Authorization: Bearer <token>

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

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

Ответы:


141

Может быть, это поможет:

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
Ладно, забудь. Очевидно, «Аутентификация» - это то, на что вы можете нажать, чтобы получить форму входа.
Роб

Итак, как мне установить значение для токена? Я попробовал curl -x get --header "Authorization: apiKey = 123", но ничего не произошло
Gobliins

2
@Gobliins вы хотите 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
К сожалению, это не работает с пользовательским интерфейсом Swagger - нажатие «Авторизовать» и предоставление голого токена сгенерируют примеры curl «Попробовать», -H "Authorization: foo"а не -H "Authorization: Bearer foo"как ответ OpenAPI 3
Эйб Фелькер

56

Аутентификация носителя в 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!).

Пользовательский интерфейс отобразит кнопку «Авторизовать», которую вы можете нажать и ввести токен на предъявителя (только сам токен без префикса «На предъявителя»). После этого будут отправляться запросы «опробовать» с Authorization: Bearer xxxxxxзаголовком.

Добавление Authorizationзаголовка программным способом (Swagger UI 3.x)

Если вы используете пользовательский интерфейс Swagger и по какой-то причине вам нужно добавить 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
Как мне реализовать это в документации по swagger, созданной flask-restplus?
Чанг Чжао

Я сомневаюсь, что ответ соответствует заданному вопросу.
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 на Swagger.

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

Итак, он обрабатывает аутентификацию как стандартный заголовок. К pathобъекту добавьте параметр заголовка:

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

И работает.


"токен приходит откуда-то" ... Меня интересует другое. Что, когда вы вошли в систему, вас перенаправили на ваш логин и перенаправили на ваш swagger 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

Мой Hackie способ решить эту проблему заключался в изменении файла 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

}

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.