Creating a parameter

Parameters define variable elements of a URL path, query parameters, headers, or a request body. You can create parameters for Paths and Path operations in your API definition.

1. Create the parameter; you can either create a parameter from scratch, or you can reference a parameter that is defined in a parameter component.
   • To create the parameter from scratch, provide the following information on the Definition tab:
     • Name: Available if you are creating a parameter component, this name defines a key that enables this parameter to be referenced from elsewhere in the API definition; the reference has the following format:

       #/components/parameters/Name

       Note: When the name of a query parameter includes the "+" special character, it is encoded as %2B (literal plus character) instead of %20 (literal space character). Therefore, to match the query parameter against the inbound URL, the encoded value is used. For example, when the name of the query parameter is a+space, the value to match in the inbound URL is a%2Bspace.
     • Parameter name (required): The name of the parameter.
     • Located In (required): The location of the parameter. Select one of the following options:
       • query: Parameters that are appended to the URL. For example, url_path?myparam=myvalue.
       • header: Custom headers that are expected as part of the request.
       • path: The parameter value is part of the operation's URL, enclosed in {}.
       • cookie: Used to pass a specific cookie value to the API.
     • Description: A description of the parameter. You can use CommonMark syntax for rich text representation.
     • Style: Describes how the parameter value will be serialized depending on the type of the parameter value. Select one of the following options:
       • matrix: Path-style parameters defined by RFC 6570.
       • label: Label style parameters defined by RFC 6570.
       • simple: Simple style parameters defined by RFC 6570.
       • form: Form style parameters defined by RFC 6570.
       • spaceDelimited: Space separated array values.
       • pipeDelimited: Pipe separated array values.
       • deepObject: Provides a simple way of rendering nested objects using form parameters.
     • Select the following options as required:
       • Required: Determines whether this parameter is mandatory. If the Located In property is set to path, this option must be selected.
       • Deprecated: Specifies that a parameter is deprecated and should be transitioned out of usage.
       • Allows Empty Value: Allows sending a parameter with an empty value. This is valid only if the Located In property is set to query.
       • Explode: When selected, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.
       • Allow Reserved: Determines whether the parameter value should allow reserved characters, as defined by RFC 3986 (:/?#[]@!$&'()*+,;=) to be included without percent-encoding. This property applies only if the Located In property is set to query.
   • To reference a parameter that is defined in a parameter component, provide the following information on the Reference tab:
     • Name: Available if you are creating a parameter component, this name defines a key that enables this parameter to be referenced from elsewhere in the API definition; the reference has the following format:

       #/components/parameters/Name

       Note: When the name of a query parameter includes the "+" special character, it is encoded as %2B (literal plus character) instead of %20 (literal space character). Therefore, to match the query parameter against the inbound URL, the encoded value is used. For example, when the name of the query parameter is a+space, the value to match in the inbound URL is a%2Bspace.
     • Parameter name (required, available if you are creating a path or operation parameter): The name of the parameter.
     • Reference from: Select a reference to a parameter component.
2. Click Create.
   The parameter details are displayed for further editing; see Editing a parameter.