OpenAPIでのJWT Bearer Token認証

OpenAPIでのJWT Bearer認証

JSON Web Token（JWT）認証は、モダンなREST APIで最も一般的なセキュリティスキームです。OpenAPIはBearer Token認証を構造化して文書化する方法を提供し、クライアントやSwagger UIなどのツールが認証されたエンドポイントを理解しテストできるようにします。

セキュリティスキームの定義

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        /auth/loginから取得したJWTトークン。
        Authorizationヘッダーに次の形式で含める: Bearer <token>

bearerFormat: JWT はドキュメントツール向けのヒントであり、JWT検証を強制するものではありません。実際のトークン検証はサーバーサイドで行われます。

グローバルにセキュリティを適用

デフォルトですべてのエンドポイントに認証を要求するには：

security:
  - bearerAuth: []

このトップレベルの security ブロックは、オーバーライドされない限りすべてのエンドポイントがBearerトークンを要求することを意味します。

エンドポイントごとのセキュリティ

特定のエンドポイントでセキュリティをオーバーライドまたは削除：

paths:
  /auth/login:
    post:
      security: []   # 認証不要
      summary: ログインしてトークンを取得

  /users/me:
    get:
      security:
        - bearerAuth: []
      summary: 現在のユーザープロフィールを取得

ログインと登録のエンドポイントに security: []（空の配列）を設定すると、認証から除外されます。

複数の認証方法

APIキーとJWTの両方をサポート：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

# どちらの方法でもOK（OR論理）
security:
  - bearerAuth: []
  - apiKey: []

同じレベルに複数のスキームがリストされている場合、OR論理が使用されます — クライアントはどちらの方法でも使用できます。