Configuring the swagger file for generated endpoints

A swagger file contains a paths section that lists one or more endpoint paths. For each path, the following information is specified:

• Any path or query parameters
• Each operation supported for the path, and information about the operation

The base configuration includes a set of API-specific extension swagger files. The purpose of these files is to define swagger information for custom resources for a given API. These files are named using the pattern <API>_ext-1.0.swagger.json, where <API> is the internal name of the API. For example, the common_ext-1.0.swagger.json file is used to define swagger information for custom resources in the Common API.

(There is an exception to the previous statement. When you add endpoints to the Job API, swagger modifications are not made to a job_ext-1.0.swagger.json file, but rather to the policyperiod_ext-1.0.swagger.json file.)

When you generate endpoints for a custom entity, the REST endpoint generator adds code to the corresponding swagger extension file.

For example, suppose you generate endpoints for a CustomEntity_Ext custom entity. The parent of this entity is Account, and the endpoints are placed in the Account API. The REST endpoint generator add the following code to the account_ext-1.0.swagger.json file:

paths:
  "/account/{accountId}/custom-entities-ext":
    parameters:
    - $ref: "#/parameters/accountId"
    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"
  "/accounts/{accountId}/custom-entities-ext/{customEntityExtId}":
    parameters:
    - $ref: "#/parameters/accountId"
    - $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"

Note that this text is functionally complete and there are no "TODO RestEndpointGenerator" comments in the file. However, a developer may wish to optionally modify the file.

Modifying API documentation text

Every path and response has summary and description information. This text is used by API definition display tools, such as Swagger UI. Developers may wish to modify the summary and description values created by the REST endpoint generator to improve the user experience for other developers who are consuming these endpoints.

Removing operations

The REST endpoint generator always generates a collection endpoint with a GET and POST operation, and an element endpoint with a GET, PATCH, and DELETE operation. If you do not want any of these operations, you can remove them from the swagger file.

For example, suppose an insurer wants endpoints to support CustomEntity_Ext, but they do not want to expose the ability to delete CustomEntity_Ext instances. In this case, the developer could remove the "delete" declaration from the swagger file.