The Swagger root object

The Swagger specification defines a root document object for the API specification. This topic describes the manner in which the object's properties affect the REST API framework. The topic also describes Guidewire-specific framework properties added to extend the root object. This topic does not duplicate root object information already described in the Swagger specification.

Default propagation of property values

Some properties on the root object serve as default values for operations on the root object. It is possible to specify properties for an operation explicitly, or, it is possible for a property to inherit its value from the root document. However, PolicyCenter only propagates a property default within a given Swagger file.

Thus, if a particular operation does not explicitly define a certain property, PolicyCenter uses the corresponding value specified in the root object as the property default value. For example, suppose that the contact-1.0 schema defines the root-level produces property as ["application/json"]. PolicyCenter treats the value of the root-level produces property as the default value for any operation defined in that file that does not explicitly specify its own produces property. Any operation within the file that does not explicitly define the produces property uses the root object ["application/json"] value as its default value.

However, if file contact_ext-1.0 combines with the contact-1.0 schema file, file contact_ext-1.0 does not inherit the produces property on the root document. This behavior ensures that root-level default values are always local to the file in which they exist and that the default values never bleed through to combining files in unexpected ways.

PolicyCenter only applies default values locally within a single file. Default properties do not propagate to operations defined in other files.

Required properties

Property Type Description Combination style
swagger string Required. Documentation only. Each Swagger file must specify the swagger property. Guidewire currently requires this value to be 2.0. Not inherited
info Info object Required if published. Documentation only. Property provides metadata about the API. Merged
basePath string Required if published. Property specifies the base path for the API when it is published. The value must start with a leading slash (/). First non-null
paths map<string, Patch item object> Required if published. Property specifies the available paths and operations for the API. The property must start with a '/' character. The property can also include multiple parts, each separated by a '/' character. Use the '{ }' syntax to specify a parameter name.
PolicyCenter constructs the full URL by concatenating the following items:
  • Application servlet context +
  • REST servlet url-mapping string (default is '/rest') +
  • basePath property +
  • Key of the paths property

For example, given the following components.

  • A servlet context of 'http://localhost:8180/pc'
  • A default url-mapping string ('/rest')
  • A basepath of '/contact/v1'
  • A paths key of '/contact/{contactId}'
  • A contactId value of 'johnsmith'
The concatenation of these components constructs the following URL:
  • http://localhost:8180/pc/rest/contact/v1/contact/johnsmith
 Merge by key

Optional properties

Property Type Description Combination style
consumes string[] Property specifies the acceptable input content types at runtime. It also becomes the default value for any operation defined in the same file that does not explicitly define the consumes property.

Each member of the array must be a valid MIME type.

 Not inherited
externalDocs External documentation object

Documentation only.

 First non-null
definitions map<string, JSON schema object> Property defines JSON schema definitions inline. You reference schema definitions defined inline without an alias prefix, for example:
  • #/definitions/name
 Merged using the rules defined in JSON schema file specification.
host string Property hard codes the host property as PolicyCenter retrieves the Swagger file at runtime. If not provided, PolicyCenter uses the host serving the Swagger schema as the value.
The host property value:
  • Must be a valid host name, with no schema or sub-path.
  • Can optionally include a port number.
 First non-null
parameters map<string, Parameter object>
Property defines shared parameter definitions. To reference a parameter definition, use the following syntax:
  • #/parameters/name

The name variable identifies the actual parameter definition to reference.

 Merge by key
produces string[] Property specifies the output types that the caller can request in the Accept header. The negotiated content type can affect how PolicyCenter serializes certain object types. For example, this property can affect whether PolicyCenter serializes a JsonObject or TransformResult object type as JSON or XML. The property acts as the default value for any operation defined in this same file that does not explicitly define the produces property.

Each member of the array must be a valid MIME type.

 Not inherited
responses map<string, Response object>
Property defines shared response definitions. To reference a response definition, use the following syntax
  • #/responses/name

The name variable identifies the actual response definition to reference.

 Merge by key
schemes string[] Property hard-codes the schemes[] property as PolicyCenter retrieves the Swagger schema at runtime. If not provided, PolicyCenter uses the schema requesting the Swagger schema as the value.
Each array entry must one of the following types:
  • http
  • https
  • ws
  • wss
 First non-null
security Security requirements object[]

Documentation only.

 First non-null
securityDefinitions map<string, Security scheme object>

Documentation only. Property defines the keys that specify the names of the security schemes.

 Merge by key
tags Tag object[]

Documentation only.

 Merged by tag name

Guidewire extension properties

Property Type Description Combination style
x-gw-apihandlers string[]

Property defines the default list of API handler classes. PolicyCenter searches the list, in order, to determine the handler class to use as it binds an operation to a handler. Each array entry must be a valid Gosu or Java class name.

PolicyCenter uses the root object list only if the individual operation does not specify an overriding x-gw-apihandlers property.

 First non-null
x-gw-combine string[]

Property defines additional APIs to combine with the contents of this file.

 Not inherited
x-gw-cors-policy string Property specifies the default CORS policy for all paths in the API, unless overridden at the path level. If you do not specify a CORS policy for the API or path, PolicyCenter disables CORS for that endpoint. First non-null
x-gw-cors-policies map<string, CORS policy object> Property defines the CORS policies that you can reference in the document root or in the path. Merge by key
x-gw-parameters-sets map<string, Parameter object[]> Property defines a named list of parameters that PolicyCenter can then use in an operation. Merge by key - PolicyCenter then combines the array of parameters in the set as specified by the rules for parameters on a path or operation
x-gw-permissions string[]

Property defines the default list of system permissions a user must have to request a particular operation. Each member of the array must reference a valid SystemPermissionType typecode.

If the authenticated user does not have the required permissions to request an operation, the operation returns a 403 Forbidden error.

PolicyCenter uses the root object list only if the individual operation does not specify an overriding x-gw-permissions property.

 Not inherited
x-gw-runlevel string

Property specifies the required run level of the server in order to process an operation. If the server is not at the specified run level for the requested operation, the operation returns a 503 Service Unavailable error. PolicyCenter uses this property value as the default value for any operation that does not specify the x-gw-runlevel explicitly.

PolicyCenter supports the following server run levels:
  • NONE
  • GUIDEWIRE_STARTUP
  • NODAEMONS
  • DAEMONS
  • MULTIUSER

If the root document or operation does not specify the x-gw-runlevel property, PolicyCenter uses the NODAEMONS (maintenance) run level as the default value.

 Not inherited
x-gw-schema-combine string[]
Property specifies additional JSON schemas to combine inline into this Swagger schema. Adding schemas in this fashion:
  • Makes the JSON schema definitions available without a prefix.
  • Combines the JSON definitions with any schema definitions in the file.

Each member of the array must be a fully qualified name of a JSON schema.

 Not inherited
x-gw-schema-import map<string1, string2>

Property maps an alias (string1) to a JSON Schema name (string2). You can then use the alias to reference definitions in the Schema. The property key (string1) can be any string. The property value (string2) must be a fully-qualified JSON Schema.

 Merge by key
x-gw-serialization Object for serialization

Property defines default serialization options for any operation that does not specify the x-gw-serialization property explicitly.

Not inherited