生成エンドポイントの 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 ファイルに次のコードを追加します。

paths:
  "/claims/{claimId}/custom-entities-ext":
    parameters:
    - $ref: "#/parameters/claimId"
    get:
      summary: "Retrieve a collection of custom entities ext"
      description: "Retrieve a collection of custom entities ext"
      operationId: getCustomEntitiesExt
      x-gw-extensions:
        childResourceType: CustomEntityExt
        operationType: get-collection
        resourceType: CustomEntitiesExt
      x-gw-parameter-sets: get-collection
      responses:
        "200":
          description: "Successful response"
          schema:
            $ref: "#/definitions/CustomEntityExtList"
    post:
      summary: "Create a new custom entity ext"
      description: "Create a new custom entity ext"
      operationId: createCustomEntityExt
      x-gw-extensions:
        childResourceType: CustomEntityExt
        operationType: post-collection
        resourceType: CustomEntitiesExt
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: "#/definitions/CustomEntityExtRequest"
      x-gw-parameter-sets: post-collection
      responses:
        "201":
          description: "The details of the newly-created CustomEntityExt"
          schema:
            $ref: "#/definitions/CustomEntityExtResponse"
  "/claims/{claimId}/custom-entities-ext/{customEntityExtId}":
    parameters:
    - $ref: "#/parameters/claimId"
    - $ref: "#/parameters/customEntityExtId"
    get:
      summary: "Retrieve details of a custom entity ext"
      description: "Retrieve details of a custom entity ext"
      operationId: getCustomEntityExt
      x-gw-extensions:
        operationType: get-element
        resourceType: CustomEntityExt
      x-gw-parameter-sets: get-element
      responses:
        "200":
          description: "Successful response"
          schema:
            $ref: "#/definitions/CustomEntityExtResponse"
    patch:
      summary: "Update a custom entity ext"
      description: "Update a custom entity ext"
      operationId: updateCustomEntityExt
      x-gw-extensions:
        operationType: patch-element
        resourceType: CustomEntityExt
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: "#/definitions/CustomEntityExtRequest"
      x-gw-parameter-sets: patch-element
      responses:
        "200":
          description: "Successful response"
          schema:
            $ref: "#/definitions/CustomEntityExtResponse"
    delete:
      summary: "Delete a custom entity ext"
      description: "Delete a custom entity ext"
      operationId: deleteCustomEntityExt
      x-gw-extensions:
        operationType: delete-element
        resourceType: CustomEntityExt
      x-gw-parameter-sets: delete-element
      responses:
        "204":
          description: "Successful deletion"
Java

このテキストは機能的に完全なのでファイルには「TODO RestEndpointGenerator」のコメントがないことに注意してください。ただし、開発者は任意でファイルを変更することが可能です。

API ドキュメントテキストの変更

パスと応答にはそれぞれ、summarydescription の情報があります。このテキストは、Swagger UI などの API 定義表示ツールで使用されます。REST エンドポイントジェネレータが作成した summary および description の値を開発者は変更して、そのエンドポイントを使用している他の開発者のユーザーエクスペリエンスを高めることが可能です。

操作の削除

REST エンドポイントジェネレータで必ず生成するものは、GET と POST の操作によるコレクションエンドポイント、ならびに GET、PATCH、および DELETE の操作による要素エンドポイントです。これらのいずれかの操作が不要な場合は、swagger ファイルから削除できます。

例えば、エンドポイントで CustomEntity_Ext をサポートすることを保険会社は望んでいるが、CustomEntity_Ext インスタンスの削除機能を公開することは望んでいないとします。この場合、開発者は swagger ファイルから "delete" 宣言を削除できます。