web-dev-qa-db-ja.com

Swagger Spec（swagger.json）で 'Authorization：Bearer <token>'を表す方法を教えてください。

認証/セキュリティスキームでは、次のようにヘッダーを設定する必要があることを伝えようとしています。

Authorization: Bearer <token>

これは私が swaggerドキュメント に基づいて作成したものです。

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []
swaggerswagger-2.0swagger-editor
88
Elmer Thomas

多分これは助けることができる：

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エディタのWebには、より複雑なセキュリティ設定を含むいくつかの例があります。

110
David Lopez

OpenAPI 3.0.0でのベアラ認証

OpenAPI 3. は現在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仕様の場合のみです）。

UIに「認証」ボタンが表示されます。このボタンをクリックしてベアラトークンを入力できます（「ベアラ」プレフィックスを付けずにトークン自体のみ）。その後、 "try it out"リクエストは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
  }
})
29
Helen

「受理された回答」が機能するのはなぜでしょう...しかし私にとっては十分ではありませんでした

これは仕様で機能します。少なくともswagger-tools（バージョン0.10.1）はそれを有効なものとして検証します。

しかし、swagger-codegen（バージョン2.1.6）のような他のツールを使っているのであれば、生成されたクライアントがAuthenticationの定義を含んでいても、いくつか問題があります：

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

メソッド（エンドポイント）が呼び出される前にトークンをヘッダーに渡す方法はありません。この関数シグネチャを調べてください。

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

つまり、トークンなしでコールバック（他のケースではクエリパラメータなど）を渡すだけで、サーバーへの要求が正しく構築されません。

私の選択肢

残念ながら、それは「きれい」ではありませんが、SwaggerでJWTトークンのサポートを得るまではうまくいきます。

注：これはで議論されています

それで、それは標準的なヘッダのように認証を扱います。 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
  };
  // ...
}

この方法を正しく使うには、 "full string"を渡してください。

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

そして働きます。

15
Paulo Oliveira