Skip to content

URI Template support in parameters #804

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jan 27, 2017
Merged

URI Template support in parameters #804

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9952f5a
URI Template support in parameters
darrelmiller Sep 30, 2016
828583a
Introduced prefix and separator
darrelmiller Oct 8, 2016
8616a99
Merged
darrelmiller Nov 17, 2016
89a94bd
Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into …
darrelmiller Nov 18, 2016
79cd9fa
uri template stuff
darrelmiller Nov 18, 2016
840de94
Style parameter
darrelmiller Dec 12, 2016
c815866
Updates to style parameter
darrelmiller Dec 21, 2016
65e7d0b
Updates based on review
darrelmiller Jan 24, 2017
5ba0fd8
Updates based on comments
darrelmiller Jan 24, 2017
3a8fcbb
Fixed camelCase in examples
darrelmiller Jan 24, 2017
9adb4aa
changed primitive back to string in style example
darrelmiller Jan 24, 2017
33b79aa
Added commaDelimited example
darrelmiller Jan 24, 2017
b017b27
Updated parameter to have schema as a child property
darrelmiller Jan 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 55 additions & 30 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -529,7 +529,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
"items": {
"type": "string"
},
"collectionFormat": "csv"
"style": "comma-delimited"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change to camelCase

}
]
}
Expand Down Expand Up @@ -561,9 +561,9 @@ parameters:
description: ID of pet to use
required: true
type: array
format: form
items:
type: string
collectionFormat: csv
type: string
```

#### <a name="operationObject"></a>Operation Object
Expand Down Expand Up @@ -737,8 +737,6 @@ There are four possible parameter types.
* Header - Custom headers that are expected as part of the request.
* Cookie - Used to pass a specific cookie value to the API.

For complex parameter schemas, a serialization strategy is required.
For all types, a serialization strategy must be declared.

##### Fixed Fields
Field Name | Type | Description
Expand All @@ -748,35 +746,60 @@ Field Name | Type | Description
<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
<a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`.


The content of the parameter is specified in one of two ways. By passing a schema and content-type, complex parameters may be serialized and passed:
The rules for serialization of the parameter are specified in one of two ways.
For simpler scenarios, a `Style` and `Schema` can be used to describe the structure and syntax of the parameter.

Field Name | Type | Description
---|:---:|---
<a name="parameterContent"></a>content | [Content Object](#contentObject) | The content of the request body.
<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value.
<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. The default value is false.
<a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.

By defining a subset of JSON-schema properties:
For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter.

Field Name | Type | Description
---|:---:|---
<a name="parameterType"></a>type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"file"`.
<a name="parameterFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`.
<a name="parameterItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array.
<a name="parameterDefault"></a>default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter.
<a name="parameterMaximum"></a>maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
<a name="parameterExclusiveMaximum"></a>exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
<a name="parameterMinimum"></a>minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
<a name="parameterExclusiveMinimum"></a>exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
<a name="parameterMaxLength"></a>maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26.
<a name="parameterMinLength"></a>minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29.
<a name="parameterPattern"></a>pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33.
<a name="parameterMaxItems"></a>maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42.
<a name="parameterMinItems"></a>minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45.
<a name="parameterUniqueItems"></a>uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49.
<a name="parameterEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
<a name="parameterMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
<a name="parameterContent"></a>content | [Content Object](#contentObject) | The content of the request body.

In order to support common ways of serializing simple parameters, a set of `style` values are defined.

`style` | [`type`](#dataTypeType) | `in` | Comments
----------- | ------ | -------- | --------
matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
form | `primitive`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
commaDelimited | `array` | `query`, `path` | Comma seperated array values. This option replaces `collectionFormat` equal to `csv`.
spaceDelimited | `array` | `query` | Space seperated array values. This option replaces `collectionFormat` equal to `ssv`.
pipeDelimited | `array` | `query` | Pipe seperated array values. This option replaces `collectionFormat` equal to `pipes`.
deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.


##### Style Examples

Assuming a parameter named `color` with one of the following values:

```
string -> "blue"
array -> ["blue","black","brown"]
object -> { "R" : 100, "G" :200, "B" : 150 }
```
The following table shows examples of how those values would be rendered.

[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Header should be primitive instead of string

----------- | ------ | -------- | -------- | --------|-------
matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150
matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150
label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150
form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150
commaDelimited | false | n/a | n/a | blue,black,brown | R,100,G,200,B,150
spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150
pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150
deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150

This object can be extended with [Specification Extensions](#specificationExtensions).

Expand All @@ -797,7 +820,7 @@ A header parameter with an array of 64 bit integer numbers:
"format": "int64"
}
},
"collectionFormat": "csv"
"style": "commaDelimited"
}
```

Expand All @@ -811,7 +834,7 @@ schema:
items:
type: integer
format: int64
collectionFormat: csv
style: commaDelimited
```

A path parameter of a string value:
Expand Down Expand Up @@ -849,7 +872,8 @@ An optional query parameter of a string value, allowing multiple values by repea
"type": "string"
}
},
"collectionFormat": "multi"
"style": "form",
"explode": true
}
```

Expand All @@ -862,7 +886,8 @@ schema:
type: array
items:
type: string
collectionFormat: multi
style: form
explode: true
```

A form data with file type for a file upload:
Expand Down