Estou tentando transmitir que o esquema de autenticação / segurança requer a configuração de um cabeçalho da seguinte maneira:

Authorization: Bearer <token>

Isso é o que eu tenho com base na documentação do swagger :

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

Talvez isso possa ajudar:

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'

Você pode copiar e colar aqui: http://editor.swagger.io/#/ para verificar os resultados.

Existem também vários exemplos na web do editor de swagger com configurações de segurança mais complexas que podem ajudá-lo.

Autenticação do portador em OpenAPI 3.0.0

OpenAPI 3.0 agora suporta autenticação Bearer / JWT nativamente. É definido assim:

openapi: 3.0.0
...

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

security:
  - bearerAuth: []

Isso é compatível com Swagger UI 3.4.0+ e Swagger Editor 3.1.12+ (novamente, apenas para especificações OpenAPI 3.0!).

A IU exibirá o botão "Autorizar", no qual você pode clicar e inserir o token do portador (apenas o próprio token, sem o prefixo "Portador"). Depois disso, as solicitações de "teste" serão enviadas com o Authorization: Bearer xxxxxxcabeçalho.

Adicionando Authorizationcabeçalho de forma programática (Swagger UI 3.x)

Se você usar a IU Swagger e, por algum motivo, precisar adicionar o Authorizationcabeçalho programaticamente em vez de fazer os usuários clicarem em "Autorizar" e inserir o token, você pode usar o requestInterceptor. Esta solução é para Swagger UI 3.x ; UI 2.x usava uma técnica diferente.

// index.html

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

  requestInterceptor: (req) => {
    req.headers.Authorization = "Bearer xxxxxxx"
    return req
  }
})

Por que "Resposta aceita" funciona ... mas não foi o suficiente para mim

Isso funciona na especificação. Pelo menos swagger-tools(versão 0.10.1) o valida como válido.

Mas se você estiver usando outras ferramentas como swagger-codegen(versão 2.1.6) encontrará algumas dificuldades, mesmo que o cliente gerado contenha a definição de Autenticação, como esta:

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

Não há como passar o token para o cabeçalho antes que o método (ponto de extremidade) seja chamado. Olhe para esta assinatura de função:

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

Isso significa que eu apenas passo o retorno de chamada (em outros casos, parâmetros de consulta, etc.) sem um token, o que leva a uma construção incorreta da solicitação para o servidor.

Minha alternativa

Infelizmente, não é "bonito", mas funciona até que eu obtenha suporte para tokens JWT no Swagger.

Nota: que está sendo discutido em

• segurança: adicionar suporte para cabeçalho de autorização com esquema de autenticação do portador # 583
• Extensibilidade das definições de segurança? # 460

Portanto, ele trata a autenticação como um cabeçalho padrão. No pathobjeto, anexe um parâmetro de cabeçalho:

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'

Isso irá gerar um cliente com um novo parâmetro na assinatura do método:

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

Para usar este método da maneira certa, basta passar a "string completa"

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

E funciona.

Postando a resposta de 2020 em JSON usando openapi 3.0.0:

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


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

Minha maneira Hackie de resolver isso foi modificando o arquivo swagger.go no pacote echo-swagger no meu caso:

Na parte inferior do arquivo, atualize a função window.onload para incluir um requestInterceptor que formata corretamente o 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

}