Guidewire Swagger specification
x-gw-
are Guidewire extensions to the core Swagger 2.0 specification. The Swagger 2.0 specification
specifies all other properties that are not Guidewire extensions.Swagger file combination
An API contract can span multiple Swagger files. PolicyCenter combines the separate Swagger files as it generates the final, complete contract for a REST API. The simplest method of combining files is a straight, linear concatenation of each file's contents, appending one file after the other.
It is possible for PolicyCenter to interpret the concatenated contents of the contract file on an individual property basis. PolicyCenter uses this behavior to intelligently merge property definitions that span multiple files using a variety of combination techniques or styles. The following list describes the combination styles that PolicyCenter supports.
| Merge style | Description |
|---|---|
| Merge | PolicyCenter merges child objects based on the rules for combining the object. |
| Merge by key | PolicyCenter matches objects based on keys in a map. For example, PolicyCenter merges elements under "paths" with the same key. |
| Merge by <x> | PolicyCenter uses a key (a tag name or a
parameter such as $ref/name/id) to match equivalent items to merge.
PolicyCenter primarily uses this combination style
for lists of objects. |
| Merge of extensions | PolicyCenter merges extensions objects by taking the first defined value for each key, even if the defined value is null. |
| First non-null | As PolicyCenter merges N multiple objects, PolicyCenter assigns the first non-null value to the property that it finds for that object. |
| Not inherited |
PolicyCenter uses this style, in general, for default values defined in a root object that it must not propagate with the file. Thus, the property explicitly does not inherit across files. |
| N/A | PolicyCenter treats the entire object that contains the property as an atomic unit and does not merge the object. PolicyCenter primarily uses this style for a child object contained within a parent object. PolicyCenter never merges the properties of the child object individually. However, it is possible to replace the entire child object as a whole. |
Specifying properties while combining object definitions
If an object definition spans multiple files, properties defined in one file do not need to be respecified in the other files. For example, if a file adds a property to an object defined in another file, you only need to specify the added property in the second file.
A best practice is to specify the required properties for an object in the file that initially defines the object.
'Required if published'
- If file published-apis.yaml lists the schema as published, PolicyCenter requires that property.
- If file published-apis.yaml does not list the schema, PolicyCenter does not require that property.
- By specifying the property directly
- By inheritance from a combined schema
You see the phrase Required if published in Required properties reference tables in the documentation on the Swagger specification.
'Documentation only'
The Swagger specification defines many properties that have no effect on the resulting REST API contract or the framework's runtime behavior. It is still possible to specify the properties for purposes that lie outside the domain of the framework, such as consumption by third-party tools. The REST API framework ignores the values of these properties and passes their values through unmodified while parsing the Swagger file. Guidewire indicates this type of property as Documentation only.
You see the phrase Documentation only in Optional properties reference tables in the documentation on the Swagger specification.