スキーマメタデータ

InsuranceSuite システム API を使用する開発者は、Swagger UI や Postman 以外のツールを使用して API メタデータを操作したい場合もあるかもしれません。代わりのツールで作業する場合、以下の機能が役立つ可能性があります（/swagger.json エンドポイントは以下のクエリパラメータをサポートしていません。サポートしているのは、/openapi.json エンドポイントのみです）。

スキーマのレンダリングの代替オプション

クエリパラメータは、HTTP 要求に追加してデフォルトの応答を変更する式です。/openapi.json エンドポイントは以下のクエリパラメータをサポートします。これらのパラメータを使用して、スキーマメタデータのレンダリング方法を変更できます。

  • filterByUser：このユーザーの権限によってエンドポイントおよびスキーマのプロパティをフィルタリングするかどうかを指定します。
    • デフォルトは false です。
  • prettyPrint：返されるスキーマを「整形表示」して、拡大しながら読みやすくするかどうかを指定します。
    • デフォルトは false です。

HTTP 要求にクエリパラメータを追加するには、次の構文を使用します。

?<parameterName>=<value>

その他のクエリパラメータを HTTP 要求に追加するには、初回後の各クエリパラメータに以下の構文を使用します。

&<parameterName>=<value>

例えば、以下の HTTP 要求は Common API のメタデータを取得します。また、filterByUser と prettyPrint を有効にします。

http://localhost:8080/cc/rest/common/v1/openapi.json?filterByUser=true&prettyPrint=true

スキーマメタデータから SDK への変換

openapi-generator などの一部のツールは、Swagger スキーマを使用して SDK（ソフトウェア開発キット）を出力できます。/openapi.json エンドポイントは以下のクエリパラメータをサポートします。これらのパラメータを使用して、SDK のレンダリング方法を変更できます。

  • enablePolymorphism：有効なフィールドのセットがデータの属性（国、サブタイプなど）によって変化する可能性がある場合に、discriminator/oneOf パターンを使用してスキーマを出力するかどうかを指定します。
    • デフォルトは true です。
    • false に設定すると、これらの場合におけるスキーマにすべての有効なフィールドのスーパーセットが含まれます。例えば、Address スキーマは、国ごとに異なるスキーマが用意されるのではなく、すべての国のすべてのフィールドが含まれます。
    • false に設定すると、OpenAPI スキーマのその部分をサポートしないツールにもスキーマの出力を使用できるようになる可能性があります。

HTTP 要求にクエリパラメータを追加するには、以下の構文を使用します。

?<parameterName>=<value>

例えば、以下の HTTP 要求は Common API のメタデータを取得します。また、ポリモーフィズムを無効化します。

http://localhost:8080/cc/rest/common/v1/openapi.json?enablePolymorphism=false

（openapi-generator の詳細については、https://github.com/OpenAPITools/openapi-generator/ を参照してください）