OpenAPI: OAuth2認可コードフロー

OpenAPIでのOAuth2認可コードフローの文書化

認可コードフローは、サーバーサイドアプリケーションとSPA向けの推奨OAuth2フローです。OpenAPI 3.0にはOAuth2セキュリティスキームの文書化の組み込みサポートがあります。

OAuth2セキュリティスキーム

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          refreshUrl: https://auth.example.com/token
          scopes:
            read:users: Read user profiles
            write:users: Create and update users
            read:orders: Read order history
            write:orders: Create and manage orders
            admin: Full administrative access

エンドポイントへのスコープ適用

paths:
  /users:
    get:
      summary: List users
      security:
        - OAuth2:
            - read:users
      responses:
        '200':
          description: User list
    post:
      summary: Create user
      security:
        - OAuth2:
            - write:users
      responses:
        '201':
          description: User created
  /admin/settings:
    get:
      security:
        - OAuth2:
            - admin

スコープの命名規則

resource:actionのような階層的な命名パターンを使用します：

• read:users - ユーザーデータの読み取りアクセス
• write:users - ユーザーデータの作成/更新
• delete:users - ユーザーデータの削除
• admin - フルアクセス

フローの比較

フロー	最適な用途
Authorization Code	サーバーサイドWebアプリ、バックエンド付きSPA
Client Credentials	サーバー間（ユーザーコンテキストなし）
Implicit（非推奨）	レガシーSPA
PKCE	モバイルアプリ、シングルページアプリケーション

APIがサポートするフローを文書化し、API説明にセットアップ手順を提供します。