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 形式を使用します。
components.securitySchemesに Bearer スキームを追加します。1
2
3
4
5
6components:
securitySchemes:
Bearer:
type: http
scheme: bearer
description: Credentials or access token for API
2. Bearer スキームを使用する API を指定します。
1 | paths: |
※ ルートレベルのsecurityを定義すると、すべての API に適用されます。
1 | security: |
記述する場所を分かりやすくするため、簡単な図で表現すると以下のようになります。
OpenAPI Object の詳細はこちらでご確認ください。
ご参考までに、OpenAPI (Swagger) 2 では、ルートレベルにsecurityDefinitionsを定義して各 API に指定します。OpenAPI 3 になって項目が多少変わっていますので注意が必要です。
いかがだったでしょうか。
前回の記事に続き、Swagger UI を利用する便利さをお伝えしたく、WebAPI 呼び出しに Bearer トークンが必要となる場合の API 定義について記事にしてみました。最後まで読んでいただきありがとうございました。