Swagger2.0でbearerトークン認証の定義を書く

背景

以下の続きです。

SwaggerUIでBearerToken認証ができるようにするのが目的です。

環境

Rails 6.0.3.3
Swagger 2.0 // apipieが出力するのがSwagger2.0のため

正しいSwagger定義ファイルを作る

apipieのリファレンスを見ましたが、BearerToken認証に関係しそうなあ記述は見つけられませんでした。話を切り分けるため、手作業でSwagger定義を作成することにしました。

前提知識 - BearerToken認証

Bearer Tokenとは？

簡潔にまとめるとこんな感じ↓

セキュリティトークンの1つ
利用可否が「トークンの所有」のみで決定される
- 切符のようなもの（切符を持つ人が電車に乗れる）
PoP(Proof-of-Possession)トークンが対比概念
- 国際線チケットのようなもの（チケットの他にパスポートが必要）

cf. Bearerトークン - Wikipedia

Rails側の実装

ActionController::HttpAuthentication::Token を利用します。

HTTPリクエストでAuthorization Bearerヘッダーに埋め込んだトークンを使って認証します。以下コード例↓

def authenticate_token
  authenticate_with_http_token do |token, _|
    User.find_by(token: token).tap do |user|
      @current_user = user
    end
  end
end

Swagger Bearer Authentication

リファレンスから探すが、参考になりそうなものは見つけられず...。

cf. OpenAPI Specification - Version 2.0 | Swagger

もう少し調べる。以下のように書くと良さそう、とのこと。

"securityDefinitions": {
  "Bearer": {
    "type": "Authorization",
    "in": "header"
  }
},

(...)

"/v1/users/password": {
  "patch": { // Bearer Tokenを利用するメソッド
    "security": [
      {
        "Bearer": []
      }
    ],

cf. How can I represent 'Authorization: Bearer ' in a Swagger Spec (swagger.json) - Stack Overflow

おお、表示された！

f:id:yukke722:20210129075157p:plain