OpenAPIのエラーレスポンススキーマ
OpenAPIで一貫したエラーレスポンススキーマを設計。コード、メッセージ、フィールドレベルのバリデーションエラー、再利用可能なエラーコンポーネントを含む標準エラーオブジェクトを定義して、クリーンなAPIエラーハンドリングを実現。
Schema Patterns
詳細な説明
OpenAPIのエラーレスポンススキーマ
適切に設計されたAPIには一貫したエラーレスポンスが必要です。OpenAPIでエラースキーマをドキュメント化することで、クライアントがエラーをプログラム的に処理でき、開発者が問題発生時に何を期待すべきかを正確に把握できます。
標準エラーオブジェクト
components:
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: 機械可読なエラーコード
example: "RESOURCE_NOT_FOUND"
message:
type: string
description: 人間可読なエラーメッセージ
example: "リクエストされたユーザーが見つかりません"
details:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
description: フィールドレベルのバリデーションエラー
再利用可能なエラーレスポンス
共通のエラーレスポンスを一度定義:
components:
responses:
NotFound:
description: リソースが見つかりません
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Unauthorized:
description: 認証が必要です
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
paths:
/users/{id}:
get:
responses:
"200":
description: 成功
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
このパターンは一貫したエラードキュメントを維持しながらpathsをクリーンに保ちます。
ユースケース
一貫したエラースキーマはプロフェッショナルなAPI設計の特徴です。クライアント開発者はエラーレスポンス定義を使用して堅牢なエラーハンドリングを構築します — フォーム表示用のバリデーションエラーの解析、リダイレクトロジックのための認証失敗の検出、構造化されたエラーデータのログ記録などです。