API設計では通常、200 OK
の成功レスポンスは異なる出力データのニーズにより各APIで異なるが、400 Bad Request
や 404 Not Found
などのエラーレスポンスは異なるAPI間で一貫している傾向がある。Apidogは レスポンスコンポーネント
機能でこの共通性に賢く対応し、事前定義されたエラーレスポンスの再利用を可能にすることで、APIドキュメント作成プロセスをより効率的にし、APIの動作をより一貫したものにする。レスポンスコンポーネントの追加#
API
モジュールの左側のディレクトリツリーで、コンポーネント
セクションに移動し、レスポンス
の下の 新規レスポンス
をクリックして新しいレスポンスコンポーネントを作成できる。レスポンスコンポーネントの作成は、HTTPステータスコード
、コンテンツタイプ
、Schema
、例
を含む点で、APIの定義時のレスポンスセクションの指定と同様だ。
詳細なガイダンスについては、APIの指定のレスポンスセクションを参照できる。新規APIにデフォルトで追加: 「はい」を選択すると、このコンポーネントはプロジェクトに追加されるすべての新規APIにデフォルトで自動的に含まれる。
レスポンスコンポーネントの参照#
APIの レスポンス
セクションで、事前に定義したレスポンスコンポーネントを参照できる。参照されたレスポンスコンポーネントはAPI内で変更できない。元のレスポンスコンポーネントに変更を加える必要がある。変更を加えると、このコンポーネントを参照するすべてのAPIに影響する
APIで参照されているレスポンスコンポーネントを変更したい場合は、参照解除できる。参照解除すると、レスポンスは通常の編集可能なレスポンスになり、レスポンスコンポーネントの変更の影響を受けなくなる
APIでは、コンポーネントは1回しか参照できない。同じコンポーネントの複数のインスタンスを同じAPI内に共存させることはできない
一括操作#
既存のレスポンスコンポーネントを選択したAPIに一括で 追加
したり、選択したAPIからこのコンポーネントを一括で削除したりできる。選択したAPIがすでにこのレスポンスコンポーネントを含んでいる場合、再度追加されることはない
選択したAPIがこのレスポンスコンポーネントを含んでいない場合、削除操作は効果を持たない
デフォルトレスポンステンプレート#
多くの企業では、レスポンスの構造が標準化されている。このような場合、デフォルトレスポンステンプレートを活用して、企業の固定構造をデフォルトのレスポンステンプレートとして維持できる。左側のディレクトリツリーの コンポーネント
セクションで、デフォルトレスポンステンプレート
機能にアクセスして利用できる。新しいAPIが作成されると、このテンプレートの内容が初期レスポンスとして使用される。デフォルトレスポンステンプレートの変更は新規APIにのみ影響し、既存のものには影響しない
デフォルトレスポンステンプレートは1つだけ存在し、追加や削除はできない
初期のデフォルトレスポンステンプレートは、コンテンツタイプがJSONで、データ構造が空のObjectノードの200成功レスポンスだ。FAQ#
Q: レスポンスコンポーネントをデフォルトレスポンスとして使用できますか?A: いいえ、レスポンスコンポーネントは400、404などのステータスコードのような一般的なエラーレスポンス用です。固定のデフォルトレスポンスを使用する必要がある場合は、デフォルトレ スポンステンプレートを使用してください。 Modified at 2024-12-27 07:58:01