OpenAPI仕様書の書き方 — ビジュアル確認とデバッグのコツ
OpenAPI（旧Swagger）はRESTful APIの仕様を記述する標準フォーマットです。YAML/JSONで書かれた仕様書を人が読みやすい形式で表示することで、APIの設計・レビュー・クライアント実装の効率が上がります。
OpenAPI 3.x と Swagger 2.0 の違い
Swagger 2.0は「swagger: "2.0"」で始まる旧仕様で、basePath/host/schemesでURLを定義します。OpenAPI 3.0以降は「openapi: "3.x.x"」で始まり、serversオブジェクトで複数の環境URL、requestBodyの分離、componentsによる再利用コンポーネント管理が改善されました。現在は3.xへの移行が推奨されています。
$refと再利用コンポーネントの活用
$refは別定義を参照する仕組みで「$ref: "#/components/schemas/User"」のように使います。スキーマ・パラメーター・レスポンスを一度定義して複数箇所から参照でき、仕様書のDRY原則を守れます。OpenAPI Viewerは$refを解決して実際のスキーマ内容を展開表示するため、定義元を行き来する手間が不要です。
パラメーターの種類（in: の値）
path（URLパス中の変数：/users/{id}）、query（?key=value）、header（リクエストヘッダー）、cookie（Cookieヘッダー）の4種類があります。それぞれ異なるバリデーションルールがあり、requiredフィールドで必須かどうかを示します。body（Swagger 2.0）はOpenAPI 3.xではrequestBodyに移動しました。
APIデザインのベストプラクティス
パスはリソース名（複数形の名詞）をスラッシュで階層化し、動詞はHTTPメソッドで表します（GET /users, POST /users, DELETE /users/{id}）。レスポンスには200/201/400/401/404/500を適切に定義します。descriptionにはサンプル値と共にエラーレスポンスの例を含めると実装者にとって親切です。