OpenAPI (Swagger) 3.0 で Bearer トークンの使用を定義する

Bearer トークンを使用して WebAPI 呼び出しをする場合、OpenAPI (Swagger) 3.0 ではどのように記述するのでしょうか。

OpenAPI (Swagger) で WebAPI の仕様を記述する際、HTTP 認証・認可を行うための手段として Basic 認証・Bearer スキーム・API キー等の使用を定義することができます。この記事ではアクセストークン等による Bearer スキームの記述方法について紹介します。

※ OpenAPI (Swagger) については以下の記事で取り上げていますので、合わせてご確認ください。

Bearer スキームとは

HTTP 認証スキームの一つで、WebAPI へアクセスするためのセキュリティトークン(アクセストークン等)をAuthorization: Bearer {トークン}という形で HTTP ヘッダーにセットし、トークンの受け渡しを行う仕組みです。ここでは詳細を割愛させていただきますが、気になる方は以下をご参考ください。


やりたいこと

WebAPI の仕様として Bearer トークンの使用を明記し、Swagger UI の動作に反映させることです。Swagger UI で見ると、以下のように Authorize ボタンが表示されます。

赤枠のボタンをクリックすると以下のダイアログが表示され、Bearer トークンを入力することができます。

トークンを入れて Authorize ボタンをクリックすると、Bearer スキームが指定されている API は Swagger UI 上から Bearer トークン付きでリクエストが送信されます。

Bearer スキームの Authorization ヘッダーがついていますね。

Bearerという文字列も挿入されますので、こちらで入れる必要はありません。

記述方法

ここでは OpenAPI の記述に YAML 形式を使用します。

  1. components.securitySchemesに Bearer スキームを追加します。
    1
    components:  
    2
      securitySchemes:
    3
        Bearer:
    4
          type: http
    5
          scheme: bearer
    6
          description: Credentials or access token for API

2. Bearer スキームを使用する API を指定します。
1
paths:
2
  /users/me:
3
    get:
4
      # ...
5
      security:
6
      - Bearer: []

※ ルートレベルのsecurityを定義すると、すべての API に適用されます。

1
security:
2
- Bearer: []

記述する場所を分かりやすくするため、簡単な図で表現すると以下のようになります。
OpenAPI Object の詳細はこちらでご確認ください。

ご参考までに、OpenAPI (Swagger) 2 では、ルートレベルにsecurityDefinitionsを定義して各 API に指定します。OpenAPI 3 になって項目が多少変わっていますので注意が必要です。

いかがだったでしょうか。

前回の記事に続き、Swagger UI を利用する便利さをお伝えしたく、WebAPI 呼び出しに Bearer トークンが必要となる場合の API 定義について記事にしてみました。最後まで読んでいただきありがとうございました。