こんにちは！開発の現場で「またAPIの仕様が変わったのに、ドキュメントが追いついてない……」「古いバージョンと新しいバージョンが混ざってカオスになっている……」と頭を抱えた経験はありませんか？
今回は、API開発・テストにおいて避けて通れない「APIバージョニング戦略」と、その設計図である Swagger (OpenAPI) を使ったスマートな管理術について、現場のリアルな知見を交えて徹底解説します。
これをマスターすれば、カオスになりがちなAPIの改修・移行が劇的に楽になりますよ。さあ、一緒にプロの技を身につけましょう！
—
1. なぜAPIバージョニングとSwagger管理で躓くのか？
APIは生き物です。サービスが成長すれば、必ず仕様変更（フィールドの追加、型変更、エンドポイントの再設計など）が発生します。ここで適当なバージョン管理をしていると、フロントエンド開発者や外部の連携先との間で「聞いてないよ！」という大惨事（いわゆる爆死）が起きます。
OpenAPI（Swagger）は、単なる「お飾り仕様書」ではありません。システムの契約書（Contract）です。バージョンアップの歴史を綺麗にコード（YAML/JSON）として残し、かつ開発者が迷わない仕組みを作ることで、チーム全体の生産性は跳ね上がります。
—
2. 3大バージョニング戦略：どれを選ぶべきか？
まずは、APIのバージョンをどこで切り分けるかという「URLパス・ヘッダー・クエリ」の3つのアプローチを整理しましょう。現場のアーキテクトとして、それぞれの特徴と最適なユースケースを伝授します。
① URLパスバージョニング（王道・迷ったらこれ）
- 形式: `https://api.example.com/v1/users` vs `https://api.example.com/v2/users`
- メリット: 人間が見て一発でバージョンがわかる。ブラウザやプレーンなHTTPクライアントでそのままテストしやすい。キャッシュもしやすい。
- デメリット: リソース指向のREST原則から少し外れるという思想的な議論がある（URLはリソースを表すべきで、バージョンではないという考え方）。
- 結論: 迷ったらこれを選んでおけば間違いありません。 一般的なWebサービスやBtoC、パブリックAPIのデファクトスタンダードです。
② リクエストヘッダー・バージョニング（通好み・玄人向け）
- 形式: `Accept: application/vnd.example.v1+json` のように独自ヘッダーで指定。
- メリット: URLが汚れない。RESTの美しさを保てる。
- デメリット: ブラウザから直接叩きにくい。APIクライアントツール（PostmanやSwagger UIなど）での設定一手間が増える。
- 結論: 大規模なBtoB向けAPIや、URLの美しさにこだわりたい厳格な設計思想の現場に向いています。
③ クエリパラメータ・バージョニング（避けるべきアンチパターン）
- 形式: `https://api.example.com/users?version=1`
- メリット: 実装が楽。
- デメリット: キャッシュの効率が極端に落ちる。必須パラメータの強制が難しくなる。
- 結論: プロトタイピング以外では極力避けるべきです。
—
3. Swagger (OpenAPI) での具体的な管理術
バージョン方針が決まったら、次はそれをSwagger（OpenAPI 3.0以降）でどう表現するかです。ここからが本番のノウハウですよ！
実戦テクニック①：URLパス方式の場合の `paths` グルーピング設計
URLパスでバージョンを切る場合、ひとつのYAMLファイル内に `v1` と `v2` のパスをごちゃ混ぜに書くと、すぐにスパゲッティ状態になります。綺麗に整理された定義ファイルの断片を見てみてください。
openapi: 3.0.3
info:
title: ユーザー管理API
description: v1およびv2のエンドポイントを提供する統合API仕様書
version: “2.0.0” # API全体のドキュメントバージョン
paths:
# ==========================================
# v1 エンドポイント群（将来的に廃止予定）
# ==========================================
/v1/users:
get:
summary: 【v1】ユーザー一覧取得
description: 古い仕様のユーザー一覧を返します。
deprecated: true # 後述する非推奨アノテーション
responses:
‘200’:
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/UserV1’
# ==========================================
# v2 エンドポイント群（推奨）
# ==========================================
/v2/users:
get:
summary: 【v2】ユーザー一覧取得
description: ページングとフィルタリング性能を向上させた最新のユーザー一覧です。
parameters:
- name: limit
in: query
schema:
type: integer
default: 20
responses:
‘200’:
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/UserV2’
components:
schemas:
UserV1:
type: object
properties:
id:
type: integer
name:
type: string
UserV2:
type: object
properties:
userId:
type: string # v1のintegerからstring（UUID）に変更された想定
fullName:
type: string
createdAt:
type: string
format: date-time
実戦テクニック②：`deprecated: true` で非推奨を明確に伝える
バージョンアップで最も重要なのは、「古いバージョンをいつ、どうやって消すか」の移行期間です。
OpenAPIには、エンドポイントやプロパティが「もうすぐ使えなくなる（非推奨）」ことを示す強力なフラグ `deprecated: true` が用意されています。
これを付与しておくと、Swagger UI上で視覚的に打ち消し線が入るだけでなく、各種コードジェネレーター（OpenAPI Generatorなど）がクライアントSDKを生成する際に `@Deprecated` アノテーションを付与してくれます。開発者がコードを書く段階で「あ、このフィールドもう使っちゃいけないんだな」と気づけるわけです。
email:
type: string
deprecated: true
description: 【非推奨】v3では profile.email に移行します
実戦テクニック③：大規模化したら「別ファイル分割（$ref）」を使う
APIのエンドポイントが100個を超えてくると、1万行を超える巨大なYAMLファイルが誕生し、エディタがフリーズする地獄が訪れます。
そんなときは、`$ref` を使ってファイルをスマートに分割しましょう。
ディレクトリ構成例：
api-spec/
├── main.yaml # エントリポイント
├── paths/
│ ├── v1-users.yaml # v1のパス定義
│ └── v2-users.yaml # v2のパス定義
└── components/
└── schemas.yaml # 共通のデータモデル
`main.yaml` の記述例：
openapi: 3.0.3
info:
title: マイクロサービス統合API
version: “1.0.0”
paths:
# v1のパス定義ファイルを外部から読み込む
/v1/users:
$ref: ‘./paths/v1-users.yaml’
# v2のパス定義ファイルを外部から読み込む
/v2/users:
$ref: ‘./paths/v2-users.yaml’
このように分割することで、Gitでのコンフリクト（競合）も劇的に減り、チーム開発が驚くほどスムーズになります。
—
4. まとめ：今日からできる第一歩
APIのバージョニングとSwagger管理は、一見すると面倒くさそうに思えますが、「将来の自分とチームメイトを救うための最高への投資」です。
1. 基本は「URLパス（`/v1/`, `/v2/`）」で分かりやすく切り分ける
2. 古くなったエンドポイントやプロパティには必ず `deprecated: true` をつける
3. 肥大化したら迷わず `$ref` でファイルを分割する
この3つを意識するだけで、あなたの書くAPI仕様書は、世界一美しく、誰からも愛されるドキュメントに生まれ変わります。
ぜひ、今日からの開発に取り入れてみてください。毎日のAPI開発・テストが、驚くほど快適になりますよ！