API 定義の表示

API 定義 は、API の動作を技術的に記述したものです。API 定義には、通常、以下のものが含まれています。

  • API のエンドポイント
  • ペイロードの構成方法を規定する各エンドポイントで使用されるスキーマ
  • 各エンドポイントで使用されるリソース
  • 各リソースで使用可能なフィールド
  • 各フィールドに適用されるプロパティ

以下は、Cloud API で API 定義を表示するための一般的なアプローチです。

  • Swagger UI を使用する。
  • 要求ツールを使用して、/openapi.json エンドポイント（または /swagger.json）を呼び出す。

Swagger UI

Swagger UI は、インタラクティブな Web ページとして API 定義を提示するオープンソースツールです。Swagger UI の詳細については、次の Swagger Web サイトを参照してください。https://swagger.io/tools/swagger-ui/

Swagger UI は、ClaimCenter に自動的にバンドルされます。

Swagger UI は、スキーマ情報の表示に役立ちます。Swagger UI はその情報を階層的に表します。子スキーマは、親スキーマを基準にインデントされ、階層の個々のノードは展開したり折りたたむことができます。複雑なスキーマでの検索は、Swagger UI では比較的容易です。

ただし、Swagger UI では、ソースファイルに存在するメタデータのいくつかが取り除かれます。例えば、Guidewire 独自のタグは Swagger UI ではレンダリングされません。1 つの API ですべてのメタデータにアクセスする必要があるとき、/openapi.json エンドポイントを直接呼び出したほうがよい場合があります。

注: 要求をワーキングエンドポイントに送信して応答を観察する機能も Swagger UI にあることに注意してください。ただし、Guidewire では、Swagger UI は API 定義の表示にのみ使用することをお勧めします。Cloud API の API は極めて堅牢です。Swagger UI を使用して要求を送信すると、応答を受信するまでのパフォーマンスが許容時間を超えることがあります。推奨される要求ツールの詳細については、要求と応答を参照してください。

Swagger UI を使用した API 定義の表示

手順

  1. API のパスを特定します（各 API のパスのリストについては、Cloud API の API のリストを参照してください）。
  2. ClaimCenter を起動します。
  3. Web ブラウザに Swagger UI の URL を入力します。Swagger UI ツールが読み込まれます。
    • URL の形式は <applicationURL>/resources/swagger-ui/ です。
    • 例えば、ClaimCenter のローカルインスタンスには、http://localhost:8080/cc/resources/swagger-ui/ を使用します。
  4. Swagger UI インターフェイスの上部にあるテキストフィールドに、希望する API の swagger.json ファイルを指す URL を入力します。そして、［Explore］をクリックします。
    • URL の形式は <applicationURL>/rest<APIpath>/swagger.json です。
    • 例えば、Common API を表示するには、次のように入力します。 <applicationURL>/rest/common/v1/swagger.json

タスクの結果

以下のスクリーンショットは、Swagger UI に表示された Common API の上部を示しています。


Swagger UI のユーザーインターフェイス

Swagger UI での API 情報の構成

Cloud API のバージョン番号は、API 名の後に灰色の楕円内で上部にあります（API ごとに個別のバージョン番号が付いていないことに注意してください。Swagger UI では、Cloud API リリース全体に対するバージョン番号が表示されます）。

API 内のすべてのエンドポイントがリストに表示されます。デフォルトでは、API ごとに以下の情報が表示されます。

  • エンドポイントの操作（GET など）
  • エンドポイントのパス（/activities など）
  • エンドポイントの要約（Returns a list of activities assigned to the current user（現在のユーザーにアサインされたアクティビティのリストを返す）など）

操作ボタンをクリックすると、エンドポイントに関する追加情報が表示されます。これには、以下が含まれます。

  • さらに詳細なエンドポイントの説明
  • エンドポイントによってサポートされているクエリパラメータのリスト
  • エンドポイントによって使用されるリソースおよびスキーマの階層リスト（［モデル］タブの［応答］セクションに表示されます）

API 定義エンドポイントと Postman

状況によっては、生の API 定義情報を表示すると役立つことがあります。Cloud API では、すべての API に API 定義を返す 2 つのエンドポイントが含まれています。/openapi.json と /swagger.json です。

  • /openapi.json は、OpenAPI 3.0 仕様（OpenAPI 3.0 とも呼ばれます）を使用して API 定義を返します。
  • /swagger.json は、Swagger 2.0 仕様（Swagger 2.0 とも呼ばれます）を使用して API 定義を返します。
注: Cloud API は Swagger 2.0 仕様を使用して作成されています。ただし、各 API の定義は、Swagger 2.0 仕様（/swagger.json エンドポイントを使用）と OpenAPI 3.0 仕様（/openapi.json エンドポイントを使用）のいずれでも返すことができます。

API 定義エンドポイントは、Swagger UI で取り除かれる場合があるメタデータを含めて、すべてのエンドポイント関連メタデータを表示する場合に役立つ場合があります。ただし、API 定義エンドポイントでは、「生」の形式で情報が提示されます。色、フォント、または配置を使用して情報を分けることはできません。スキーマ階層は、Swagger UI ほど読みやすくはなりません。スキーマ階層を詳細にレビューする必要がある場合、Swagger UI を使用するほうが容易な可能性があります。

メタデータの視点からは、OpenAPI 3.0 仕様のほうが情報が豊富です。Guidewire では、どちらのエンドポイントも選択できる場合は、/openapi.json エンドポイントの使用をお勧めします。例えば、Guidewire 独自のタグ（x-gw-typelist など）は、/openapi.json 応答ではリストされますが、/swagger.json 応答ではリストされません。ただし、API メタデータのレンダリングに使用するいくつかのツールは、OpenAPI 3.0 仕様を使用して情報を処理するのに十分なほど堅牢でない場合があります。/swagger.json エンドポイントは、そのような場合に使用できます。

ベースコンフィギュレーションでは、API 定義エンドポイントは、未認証呼び出し元を含めてすべての呼び出し元から使用できます。

Postman

要求ツールを使用して API 定義エンドポイントを呼び出すことができます。要求ツールは、InsuranceSuite アプリケーションに自動的にバンドルされません。自身でダウンロードしてインストールする必要があります。

Postman は Guidewire が推奨する要求ツールです。このツールには、以下の機能があります。

• ヘッダーとペイロードを含めて API 呼び出しを保存する。

• 呼び出しのコレクションを保存する。

• Swagger スキーマファイルをインポートすることで、スキーマのパスに対して呼び出しのコレクションを自動的に作成する。

• コレクションをチームの他の開発者と共有する。

このツールの詳細およびダウンロードについては、https://www.postman.com/ を参照してください。

Postman を使用して API 定義を表示する方法

始める前に

Postman をインストールします。このツールの詳細およびダウンロードについては、https://www.postman.com/ を参照してください。

このタスクについて

このタスクには、通常、認証情報は含まれません。これは、未認証呼び出し元を含め、すべての種類の呼び出し元が API メタデータを要求できるからです。

手順

  1. API のパスを特定します（各 API のパスのリストについては、Cloud API の API のリストを参照してください）。
  2. ClaimCenter を起動します。
  3. Postman を起動します。
  4. Postman で、［Launchpad］タブの右側の［+］タブをクリックして、新しい要求を開始します。
  5. ［Untitled Request］ラベルで GET が選択されていることを確認します（これはデフォルトの操作です）。
  6. ［Enter request URL］フィールドに、次の URL を入力します。<applicationURL>/rest<APIpath>/openapi.json（または <applicationURL>/rest<APIpath>/swagger.json）。例えば、ClaimCenter のローカルインスタンスの Common API を表示するには、以下のように入力します。
    • http://localhost:8080/cc/rest/common/v1/openapi.json（または http://localhost:8080/cc/rest/common/v1/swagger.json）
  7. 要求フィールドの右側にある［送信］ボタンをクリックします。

タスクの結果

結果ペインに API 情報が表示されます。例えば、前に参照した openapi.json エンドポイントを呼び出すときの結果で最初の部分を以下に示します。

{
    "components": {
        "parameters": {
            "activityId": {
                "description": "The REST identifier for the activity, as returned via previous requests that return a list of activities\n",
                "in": "path",
                "name": "activityId",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
...

API 定義エンドポイントの出力における情報の構成

API 定義エンドポイントの出力は、「生」の JSON です。

  • API に関する一般的な情報は info セクションにあります。
  • エンドポイントのリストは paths セクションにあります。
    • エンドポイントのパスに複数の操作が含まれている場合、エンドポイントのパスは 1 回のみリストされます。各操作はその下に表示されます。
    • 例えば、Common API で、/activities/{activityId} パスには、GET と PATCH のリストがあります。
  • 要約と説明は、要約や説明の対象の横に並べて表示されます。