コンポーネント

API設計では通常、200 OK の成功レスポンスは異なる出力データのニーズにより各APIで異なるが、400 Bad Request や 404 Not Found などのエラーレスポンスは異なるAPI間で一貫している傾向がある。

Apidogは レスポンスコンポーネント 機能でこの共通性に賢く対応し、事前定義されたエラーレスポンスの再利用を可能にすることで、APIドキュメント作成プロセスをより効率的にし、APIの動作をより一貫したものにする。

Apidogのレスポンスコンポーネント機能は、OASのComponentsと互換性がある。

レスポンスコンポーネントの追加

API モジュールの左側のディレクトリツリーで、コンポーネント セクションに移動し、レスポンス の下の 新規レスポンス をクリックして新しいレスポンスコンポーネントを作成できる。

レスポンスコンポーネントの作成は、HTTPステータスコード、コンテンツタイプ、Schema、例 を含む点で、APIの定義時のレスポンスセクションの指定と同様だ。
詳細なガイダンスについては、APIの指定のレスポンスセクションを参照できる。

レスポンスコンポーネントの固有の機能：

新規APIにデフォルトで追加: 「はい」を選択すると、このコンポーネントはプロジェクトに追加されるすべての新規APIにデフォルトで自動的に含まれる。

既存のAPIはこの設定の影響を受けない。

APIの レスポンス セクションで、事前に定義したレスポンスコンポーネントを参照できる。

参照されたレスポンスコンポーネントはAPI内で変更できない。元のレスポンスコンポーネントに変更を加える必要がある。変更を加えると、このコンポーネントを参照するすべてのAPIに影響する

APIで参照されているレスポンスコンポーネントを変更したい場合は、参照解除できる。参照解除すると、レスポンスは通常の編集可能なレスポンスになり、レスポンスコンポーネントの変更の影響を受けなくなる

APIでは、コンポーネントは1回しか参照できない。同じコンポーネントの複数のインスタンスを同じAPI内に共存させることはできない

既存のレスポンスコンポーネントを選択したAPIに一括で 追加 したり、選択したAPIからこのコンポーネントを一括で削除したりできる。

選択したAPIがすでにこのレスポンスコンポーネントを含んでいる場合、再度追加されることはない

選択したAPIがこのレスポンスコンポーネントを含んでいない場合、削除操作は効果を持たない

多くの企業では、レスポンスの構造が標準化されている。このような場合、デフォルトレスポンステンプレートを活用して、企業の固定構造をデフォルトのレスポンステンプレートとして維持できる。

左側のディレクトリツリーの コンポーネント セクションで、デフォルトレスポンステンプレート 機能にアクセスして利用できる。

新しいAPIが作成されると、このテンプレートの内容が初期レスポンスとして使用される。

デフォルトレスポンステンプレートの変更は新規APIにのみ影響し、既存のものには影響しない

デフォルトレスポンステンプレートは1つだけ存在し、追加や削除はできない

初期のデフォルトレスポンステンプレートは、コンテンツタイプがJSONで、データ構造が空のObjectノードの200成功レスポンスだ。

Q: レスポンスコンポーネントをデフォルトレスポンスとして使用できますか？

A: いいえ、レスポンスコンポーネントは400、404などのステータスコードのような一般的なエラーレスポンス用です。固定のデフォルトレスポンスを使用する必要がある場合は、デフォルトレスポンステンプレートを使用してください。