こんにちは！API開発の現場で、フロントエンドや他チームとの仕様すり合わせに頭を悩ませていませんか？
「APIドキュメントが古い」「認証の仕様書がバラバラでクライアント側が実装しにくい」——そんな絶望的な状況を打破するのが、OpenAPI（旧Swagger）です。
今回は、その中でも特に事故が起きやすい「セキュリティ定義（認証・認可）」に特化して、現場で即座に使える実践的な書き方を徹底解説します。これをマスターすれば、APIの門番であるセキュリティ設計が美しくドキュメント化され、毎日のフロント・バックエンド間の泥臭いコミュニケーションが劇的に楽になりますよ。
—
1. OpenAPI 3.0系における `securitySchemes` の基本構造
OpenAPI 3.0では、API全体、あるいは特定のエンドポイントに「誰がどうやってアクセスできるか」を定義するための司令塔として、ドキュメントの根幹に `components.securitySchemes` というセクションを置きます。
ここで定義した「鍵の仕組み（スキーム）」を、個別のAPIパスで呼び出して適用する、というのが基本思想です。
まずは全体像を俯瞰するために、最も基本的な骨組みを見てみましょう。
openapi: 3.0.3
info:
title: 圧倒的にセキュアなAPIサンプル
version: 1.0.0
1. ここで「どんな鍵の種類を使うか」をグローバルに定義する
components:
securitySchemes:
# 独自の名前（例: ApiKeyAuth, OAuth2App など）を自由につけられます
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
2. 定義した鍵をAPI全体にデフォルト適用することも可能（今回は個別適用を解説するため省略）
この `components.securitySchemes` の中に、プロジェクトで必要な認証方式を並べていくことになります。それでは、現場で本当によく使われる3つのパターン（Bearer、APIキー、OAuth2）の具体的なコードを見ていきましょう。
—
2. 実践コード：3大認証パターンの書き方
① Bearer認証（HTTP / JWTなど）
現代のWeb APIで最も一般的な、JWT（JSON Web Token）などを用いたBearer認証の定義です。`type: http` と `scheme: bearer` を指定するのがポイントです。
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT # クライアントに「JWTを渡してね」と優しく伝えるヒント（任意の文字列）
description: “Authorizationヘッダーに ‘Bearer
② APIキー（Header / Query）
マイクロサービス間の通信や、シンプルなAPIキー認証の場合です。`in` プロパティで、キーを「どこに含めるか」を指定します（通常は `header` ですが、レガシーなシステムでは `query` や `cookie` の場合もあります）。
components:
securitySchemes:
ApiKeyHeaderAuth:
type: apiKey
in: header
name: X-API-KEY # リクエストヘッダーのキー名
description: “システム管理画面から発行されたAPIキーを付与してください。”
ApiKeyQueryAuth:
type: apiKey
in: query
name: api_key # クエリパラメータのキー名（例: ?api_key=your_key）
description: “URLのクエリパラメータとしてAPIキーを渡す場合”
③ OAuth2（複雑な認可フロー）
API設計で最も難解とされるOAuth2ですが、OpenAPIを使えば綺麗に整理できます。ここではWebアプリケーションなどでよく使われる `authorizationCode` フローを例にします。
components:
securitySchemes:
OAuth2Auth:
type: oauth2
description: “OAuth2によるセキュアな認可フロー”
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read:pets: “ペット情報の閲覧権限”
write:pets: “ペット情報の登録・更新権限”
OAuth2を使うときは、`flows` の中にどの認可フロー（authorizationCode, clientCredentials, implicit, password）を使うかを正確にマッピングするのがコツです。
—
3. 特定のエンドポイントだけにセキュリティを適用・除外する方法
「ログインAPIやヘルスチェック（死活監視）は認証なしで叩かせたいけれど、ユーザー情報取得APIはBearer認証を必須にしたい」——このような要件は実務で必ず出てきます。
OpenAPIでは、グローバル（API全体）にセキュリティをかけつつ特定のエンドポイントで除外するパターンと、エンドポイントごとに個別に適用するパターンがあります。ここでは最も安全でコントロールしやすい「個別適用・除外」のスマートな書き方を紹介します。
openapi: 3.0.3
info:
title: 選択的セキュリティ適用サンプル
version: 1.0.0
paths:
# 1. 誰でもアクセスできる公開エンドポイント（セキュリティ定義を空配列 `[]` にする）
/public/health:
get:
summary: ヘルスチェック
security: [] # ← これにより、グローバル設定に関わらず認証が完全にバイパスされます
responses:
‘200’:
description: 正常稼働中
# 2. Bearer認証が必須のエンドポイント
/users/me:
get:
summary: ログイン中ユーザーのプロフィール取得
security:
- BearerAuth: [] # ← componentsで定義した名前を指定
responses:
‘200’:
description: 成功
# 3. 「Bearer認証」または「APIキー」のどちらか片方があれば通るエンドポイント（OR条件）
/data/sync:
post:
summary: データ同期API
security:
- BearerAuth: []
- ApiKeyHeaderAuth: [] # リストの要素が並列＝OR条件になります
responses:
‘200’:
description: 同期成功
ここがプロの知見：AND条件とOR条件の罠
YAMLのリスト構造のインデントには細心の注意を払ってください。
- OR条件（どれか一つの認証を通ればOK）：
security:
- SchemeA: []
- SchemeB: []
- AND条件（すべての認証を同時にクリアする必要がある）：
security:
- SchemeA: []
SchemeB: []
この違いを間違えると、クライアント側から「認証通らないんだけど！」と無駄なデバッグの時間を奪うことになります。必ずチームで共有しましょう。
—
まとめ
今回は、Swagger (OpenAPI) における `securitySchemes` の基本構造から、3大認証パターンの具体的なコード、そして実務で必須となるエンドポイントごとの適用・除外テクニックまで解説しました。
- `components.securitySchemes` で鍵のカタログを作る
- 各パスの `security` プロパティで鍵をガチャっとはめ込む
- 公開APIには `security: []` を明示してバグを防ぐ
このルールさえ頭に叩き込んでおけば、どんなに複雑な権限管理を持つ大規模APIであっても、美しく、誰が見ても一目でわかるドキュメントを構築できます。
Swaggerの仕様書が綺麗になると、フロントエンドエンジニアからの質問チャットが驚くほど減り、あなた自身の開発スピードも加速します。ぜひ、今日の設計から取り入れてみてくださいね！