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設計の特徴です。クライアント開発者はエラーレスポンス定義を使用して堅牢なエラーハンドリングを構築します — フォーム表示用のバリデーションエラーの解析、リダイレクトロジックのための認証失敗の検出、構造化されたエラーデータのログ記録などです。

試してみる — OpenAPI Editor & Viewer

フルツールを開く