Swagger and apiconfig files

Swagger files and apiconfig files do not directly define schema behavior. But they do contain information related to schemas. For the sake of completeness, they are defined here.

Swagger files

Within the context of Cloud API, a swagger file defines the endpoints and operations for a given API. Typically, there is no need for an insurers to configure a Cloud API swagger file.

Swagger files are stored in the /apis subdirectory.

Swagger file syntax

A swagger file can contain a section that defines an API. For example, the following is a portion of the common_pl-1.0.swagger.yaml file, which defines the Common API.

swagger: "2.0"
info:
  title: "Common API"
  description: "APIs for common InsuranceSuite platform objects like activities and notes"
  version: "1.4.0"
basePath: /common/v1
consumes:
- application/json
produces:
- application/json

A swagger file can also contain a paths section, which defines a set of endpoint paths and the associated operations and resources for that path. For example, the following is a portion of the common_pl-1.0.swagger.yaml file, which defines the first path in the Common API, /activities.

paths:
  /activities:
    get:
      summary: "Retrieve the `Activity` elements that are assigned to the caller"
      description: "Retrieves the `Activity` elements that are assigned to the caller"
      operationId: getActivities
      x-gw-extensions:
        childResourceType: Activity
        operationType: get-collection
        resourceType: Activities
      x-gw-parameter-sets:
      - get-collection
      responses:
        "200":
          description: "The paginated list of `Activity` elements"
          schema:
            $ref: "#/definitions/ActivityList"

Apiconfig files

Within the context of Cloud API, an apiconfig file is a glue file that maps both resources to Gosu files. The apiconfig file is also where default sort orders for collections are defined.

The only time you need to configure an apiconfig file to connect resources to Gosu files is when you are completing a configuration for CRUD endpoints created by the REST endpoint generator. For more information, see Configuring glue and impl classes for generated endpoints.

For more information on defining default sort orders, see Making properties sortable.