生成エンドポイントの swagger ファイルのコンフィギュレーション
Cloud API のコンテキストでは、swagger ファイルは特定 API のエンドポイントと操作を定義します。
以降のセクションでは、生成エンドポイント用 swagger ファイルのコンフィギュレーションの概要を示します。swagger ファイルのコンフィギュレーション方法の完全な説明については、スキーマコンフィギュレーションの概要を参照してください。
swagger ファイル構文の概要
1 つ以上のエンドポイントパスが列挙される paths セクションが、swagger ファイルにあります。パスごとに、以下の情報が指定されます。
- パスまたはクエリパラメータ
- パスに対してサポートされている操作と操作関連情報
swagger ファイルにおける変更
ベースコンフィギュレーションには、API 固有の拡張 swagger ファイルのセットが含まれています。これらのファイルの目的は、特定の API 用のカスタムリソースに関する swagger 情報を定義することです。「<API>_ext-1.0.swagger.json」のパターンを使用してこれらのファイルに名前が付けられます。<API> は API の内部名です。例えば、common_ext-1.0.swagger.json ファイルを使用して、Common API でカスタムリソースに関する swagger 情報を定義します
カスタムエンティティ用のエンドポイントを生成すると、REST エンドポイントジェネレータが対応 swagger 拡張ファイルにコードを追加します。
例えば、CustomEntity_Ext カスタムエンティティのエンドポイントを生成するとします。このエンティティの親はクレームなので、エンドポイントは Claim API に配置されます。REST エンドポイントジェネレータは、claim_ext-1.0.swagger.json ファイルに次のコードを追加します。
このテキストは機能的に完全なのでファイルには「TODO RestEndpointGenerator」のコメントがないことに注意してください。ただし、開発者は任意でファイルを変更することが可能です。
API ドキュメントテキストの変更
パスと応答にはそれぞれ、summary と description の情報があります。このテキストは、Swagger UI などの API 定義表示ツールで使用されます。REST エンドポイントジェネレータが作成した summary および description の値を開発者は変更して、そのエンドポイントを使用している他の開発者のユーザーエクスペリエンスを高めることが可能です。
操作の削除
REST エンドポイントジェネレータで必ず生成するものは、GET と POST の操作によるコレクションエンドポイント、ならびに GET、PATCH、および DELETE の操作による要素エンドポイントです。これらのいずれかの操作が不要な場合は、swagger ファイルから削除できます。
例えば、エンドポイントでCustomEntity_Ext をサポートすることを保険会社は望んでいるが、CustomEntity_Ext インスタンスの削除機能を公開することは望んでいないとします。この場合、開発者は swagger ファイルから "delete" 宣言を削除できます。