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)トークンが対比概念
- 国際線チケットのようなもの(チケットの他にパスポートが必要)
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
おお、表示された!
ログインするユーザーのtokenを入力します。
PrefixとしてBearer
と書く必要があるので注意。
cf. Add an authorization header to your swagger-ui with Swashbuckle (revisited) | Matt's work blog
キタ━━━(゚∀゚)━━━!!
おわりに
以上、Swagger2.0でBearer Token認証の定義を書くことができ、SwaggerUIでも動作検証ができるようになりました。
なお、apipieでSecurityDefinitionsを書く方法は見つけられませんでした...。 ご存じの方がいましたらご教示位お願いしたいです。
ひとまず、apipie以外のgemを探すか、OA3を直接書くか、を試そうと思っています。