導入
API仕様書を記述している際、同じデータ構造（ユーザー情報やエラーレスポンスなど）を何度もコピー＆ペーストしていませんか？仕様書が巨大化すると、修正時に一箇所の書き換え漏れが発生し、ドキュメントと実装の乖離を招く原因になります。OpenAPIの「$ref」機能を使うことで、重複を排除し、DRY（Don’t Repeat Yourself）な設計を実現しましょう。
基礎知識
OpenAPIにおける「$ref」とは、YAMLやJSON内の他の場所や、外部ファイルに定義された情報を参照するための仕組みです。
「components/schemas」は、API全体で使い回すデータモデルを定義しておくための領域です。ここに一度定義しておけば、各エンドポイントからは「ここを参照してください」というポインタ（$ref）を置くだけで済むため、定義の変更が発生した際も一箇所の修正で全体に反映させることが可能です。
実装/解決策
実装の基本は、以下の2ステップです。
1. components/schemas に共通のスキーマを作成する。
2. エンドポイントの定義で、直接型を書く代わりに $ref を使用して参照する。
これにより、仕様書全体の行数が削減されるだけでなく、APIのデータモデルがどこにあるのか明確になり、設計の可読性が飛躍的に向上します。
サンプルプログラム
以下のYAML例は、エラーレスポンスを共通化し、エンドポイントから参照する構成です。
openapi: 3.0.0
info:
title: ユーザー管理API
version: 1.0.0
共通部品の定義場所
components:
schemas:
# 共通のエラーメッセージ構造
ErrorResponse:
type: object
properties:
code:
type: integer
message:
type: string
paths:
/users:
get:
summary: ユーザー一覧取得
responses:
'200':
description: 成功
'400':
# ここで共通スキーマを参照（$ref）
$ref: '#/components/schemas/ErrorResponse'
応用・注意点
現場での運用において、特に注意すべきポイントは以下の2点です。
1. 外部ファイルへの分割: 仕様書が極端に大きくなった場合、一つのYAMLファイルに収めるのではなく、スキーマ定義を別ファイル（例：schemas/user.yaml）に切り出し、外部参照として読み込むことを推奨します。これにより、チーム開発でのコンフリクトを減らせます。
2. 循環参照の回避: スキーマ同士で相互に `$ref` をし合うと、一部のバリデーションツールや生成ツールがエラーを起こすことがあります。設計段階で依存関係がループしていないか注意しましょう。
まずは小規模なプロジェクトから「エラーレスポンスの共通化」を試してみてください。これだけでも仕様書のメンテナンスコストは大きく下がります。
コメント