The Swagger Parameter object

The Parameter object describes a single operation parameter. The combination of the following properties uniquely define a parameter:
  • in
  • name

Required properties

Property Type Description Combination style
in string
Required. Determines the location of the parameter specification. The value must be one of the following:
  • body - The body of the request
  • formData - As form data
  • header - As a custom header
  • path - As part of the path
  • query - On the query string
 First non-null
items Items object

Required if type equals array. Defines the type of items, if the parameter is of type array.

 Merge
name string Required. Specifies the name of the parameter:
  • body parameters - The value must be body.
  • formdata parameters -
  • header parameters - The name of the custom header. HTTP header names are case-insensitive.
  • path parameters - The value must match a template variable within the path whose operation includes this parameter.
  • query parameters - The name of the query parameter on the URL.

In all cases, PolicyCenter uses this value to look for a matching parameter in the API handler method to which it can pass the runtime value.

 First non-null
schema Schema object

Required if in equals body. Defines the schema to which the request body must conform, if any.

 First non-null
type string

Required unless in equals body. Defines the base JSON type for the parameter. The combination of type, format, and x-gw-type determines how PolicyCenter deserializes the data into a Java object at runtime.

You must specify a value for this property if the parameter is in the query, path or header. Do not specify a value for this property for body parameters.

The property value must be one of the following:
  • array
  • boolean
  • file
  • integer
  • number
  • string
 First non-null

Optional properties

Property Type Description Combination style
$ref string

References a parameter defined on the Swagger root document. It is not possible to combine this property with any other properties.

Use the following syntax for the string value:
  • #/parameters/name
 First non-null
allowEmptyValue boolean

Determines if it is permissible to give this parameter an empty value. Use this property with query parameters only. The default value is false.

 First non-null
collectionFormat string
Determines what separator PolicyCenter uses for splitting parameter values if the parameter is of type array. The value must be one of the following types:
  • csv - Comma separator (default)
  • ssv - Space separator
  • tsv - Tab separator
  • pipes - The '|' character
  • multi - Multiple specifications of the parameter, which Guidewire permits for query parameters only
 First non-null
default Any

Specifies a default value for the parameter if the parameter is not specified on input. Do not use with body parameters, or, if the value of the required property is true.

At runtime, if you do not specify a value for the parameter, the default property value is available in the RequestContext object and passed to the API Handler method as if the parameter was specified on the request.

 First non-null
description string Documentation only. First non-null
enum Any[]

Specifies a list of values that the input must match. PolicyCenter turns the enum values in the schema into Java objects at runtime. It then compares these values against the input values using equals and hashCode methods.

Each member of the array must be a JSON value that PolicyCenter can parse based on the type, format, and x-gw-type values of the parameter.

 First non-null
exclusiveMaximum boolean

Determines if PolicyCenter treats the maximum value of this property as inclusive or exclusive for purposes of comparison between two values.

The default value is false, which means that PolicyCenter treats the value as inclusive. Only set a value for this property if you also specify a value for the maximum property as well.

 First non-null
exclusiveMinimum boolean

Determines if PolicyCenter treats the minimum value of this property as inclusive or exclusive for purposes of comparison between two values.

The default value is false, which means that PolicyCenter treats the value as inclusive. Only set a value for this property if you also specify a value for the minimum property as well.

 First non-null
format string

Defines the base JSON type format for the parameter. The combination of type, format, and x-gw-type determines how PolicyCenter deserializes the data into a Java object at runtime.

Do not specify a value for this property if this is a body parameter.

 First non-null
maximum number

Specifies the maximum numeric value allowed for this parameter. PolicyCenter parses this value as a fixed-point value, with no loss of precision. PolicyCenter then converts the value to an internal Java representation for the purpose of comparison at runtime.

The comparison is either inclusive or exclusive of the maximum value, depending upon the value of the exclusiveMaximum property.

Example 1. If the parameter has a type value of integer and a format value of int32, the maximum value must be a valid integer. At runtime, PolicyCenter converts the value to an integer value.

Example 2. If the parameter has a type value of string and a format value of gw-bigdecimal, PolicyCenter converts the value to BigDecimal at runtime.

Only set a value for this property if the parameter's runtime type is a numeric type.

 First non-null
maxItems integer

Specifies the maximum number of array members, inclusive. Only set a value for this property if the parameter is of type array. If specified, the value cannot be a negative number.

 First non-null
maxLength integer

Determines the maximum length of the parameter value, inclusive. Only set a value for the maxLength property if the runtime type is string. If specified, the value cannot be a negative number.

 First non-null
miniItems integer

Specifies the minimum number of array members, inclusive. Only set a value for this property if the parameter is of type array. If specified, the value cannot be a negative number.

 First non-null
minimum number

Specifies the minimum numeric value allowed for this parameter. PolicyCenter parses this value as a fixed-point value, with no loss of precision. PolicyCenter then converts the value to an internal Java representation for the purpose of comparison at runtime.

The comparison is either inclusive or exclusive of the minimum value, depending upon the value of the exclusiveMinimum property.

This property operates in an analogous manner to the maximum property.

Only set a value for this property if the parameter's runtime type is a numeric type.

 First non-null
minLength integer

Determines the minimum length of the parameter value, inclusive. Only set a value for the minLength property if the runtime type is string. If specified, the value cannot be a negative number.

 First non-null
multipleOf number

Specifies that the parameter value must be a multiple of the value of this property. PolicyCenter parses this value as a fixed-point value, with no loss of precision. PolicyCenter then converts the value to an internal Java representation for the purpose of comparison at runtime.

Set a value for this property only if the runtime type of the parameter is a numeric type.

 First non-null
pattern string

Specifies a regular expression that the input must match. PolicyCenter does not explicitly anchor the regular expression by default. If you want the regular expression to match the entire input string, then you need to explicitly anchor the expression with ^ and $.

PolicyCenter evaluates the pattern string using the Java regular expression engine. Thus, the regular expression must match the Java syntax. The Java syntax can have some minor differences from the JavaScript syntax, and, therefore, represent a slight deviation from the Swagger specification.

Only set a value for the pattern property if the parameter has a runtime type of string.

 First non-null
reqired boolean

If set to true, PolicyCenter requires this parameter on the request. If this parameter is missing from the request, PolicyCenter rejects the request with a 400 error

Set this property to true for path parameters.

 First non-null
uniqueItems boolean

If set to true, it indicates that each member of the array must be unique, as defined by the equals and hashCode methods of the deserialized values.

The default value is false. Only set a value for this property if the parameter is of type array.

 First non-null

Guidewire extension properties

Property Type Description Combination style
x-gw-export-enumeration boolean

If set to true, PolicyCenter writes out the typekey values as an enum property while creating the Swagger schema for external clients. A value of true is only valid if the enum property is not set and x-gw-type is a typekey type.

The default is false

 First non-null
x-gw-extensions map<string, AnyType>

The values in x-gw-extensions are available to the IRestValidatorFactoryPlugin plugin if you invoke the plugin to create custom validators for this parameter.

This value can be an arbitrary map of property keys to values. The key values can be any string, and the AnyType values can be any object, including nested JSON objects.

 Merge of extensions
x-gw-type string

Defines the base JSON type for the parameter. The combination of type, format, and x-gw-type determines how PolicyCenter deserializes the data into a Java object at runtime.

Do not specify this value for body parameters.

 First non-null