Creating the Activity API Swagger schema

The Guidewire REST API framework uses Swagger (*.swagger.yaml) files to define the API schema. Place the Swagger schema file that you create in the following directory in Guidewire Studio Project window:

configuration > config > Integrations > apis > mc > activityapi

The example Activities API uses mc/activityapi as the name space (base path) for the API configuration files that you need to create in sub-directories of the Studio Integration directory. The file names of the API configuration files that you create must also contain an ending -1.0 designation. For example, name the Swagger file that you create something similar to the following example:

activityAPI-1.0.swagger.yaml

Use the following fully qualified path to the JSON schema file in code:

mc.activityapi.activityAPI-1.0

Example Swagger schema for the Activity API

The following code sample is a working example of the Swagger schema for the Activities API. Notice that the example does not yet contain all of the required HTTP operations for this API.

swagger: '2.0'
info:
  description: "APIs for manipulating activities"
  version: '10.0'
  title: "Activities API"
basePath: /mc/activityapi
x-gw-schema-import:
  activities : mc.activityapi.activityAPI-1.0
produces:
  - application/json
consumes:
  - application/json
paths:
  /activities:
    get:
      summary: "Returns a list of activities"
      description: "Returns a list of activities"
      operationId: getActivities
      responses:
        '200':
          description: "Returns a list of activities"
          schema:
            type: array
            items:
              $ref: "activities#/definitions/ActivitySummary"
    post:
      summary: "Creates a new activity"
      description: "Creates a new activity"
      operationId: createActivity
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "activities#/definitions/NewActivity"
      responses:
        '200':
          description: "Returns the details for the newly-created activity"
          schema:
            $ref: "activities#/definitions/ActivityDetail"
  /activities/{activityId}:
    get:
      summary: "Returns details for a single activity"
      description: "Returns details for a single activity"
      operationId: getActivity
      parameters:
        - $ref: "#/parameters/activityId"
      responses:
        '200':
          description: "Returns details for a single activity"
          schema:
            $ref: "activities#/definitions/ActivityDetail"
parameters:
  activityId:
    name: activityId
    in: path
    type: string
    required: true

Important: Ensure that you use correct indention to represent the schema hierarchy. Otherwise, Studio indicates errors and the API does not function properly.