Skip to content

Commit

Permalink
Merge pull request #884 from OAI/parameter_requestBody
Browse files Browse the repository at this point in the history
Updates to parameter and requestBody
  • Loading branch information
webron authored Feb 22, 2017
2 parents 4d322ec + e5c7b1b commit d78e003
Showing 1 changed file with 36 additions and 12 deletions.
48 changes: 36 additions & 12 deletions versions/3.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -753,15 +753,15 @@ 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`.
<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](# @parameterStyle) is used, if behavior is `n/a`, the value of `allowEmptyValue` SHALL be ignored.

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.
For simpler scenarios, a [`style`](#parameterStyle) and [`schema`](#parameterSchema) can be used to describe the structure and syntax of the parameter.

Field Name | Type | Description
---|:---:|---
<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="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
<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. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, 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.
<a name="parameterExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema.
Expand All @@ -772,6 +772,7 @@ and schema of the parameter. This option is mutually exclusive with the simple
above. When `example` or `examples` are provided in conjunction with the `schema` object,
the example must follow the prescribed serialization strategy for the parameter.


Field Name | Type | Description
---|:---:|---
<a name="parameterContent"></a>content | [Content Object](#contentObject) | The content of the request body.
Expand All @@ -782,8 +783,8 @@ In order to support common ways of serializing simple parameters, a set of `styl
----------- | ------ | -------- | --------
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`.
form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value.
simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2).
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.
Expand All @@ -808,7 +809,8 @@ 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
simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150
simple | true | n/a | blue | 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
Expand Down Expand Up @@ -902,6 +904,28 @@ style: form
explode: true
```

A free-form query parameter, allowing undefined parameters of a specific type:
```json
{
"in": "query",
"name": "freeForm",
"type": "object",
"additionalProperties": {
"type": "integer"
},
"style": "form"
}
```

```yaml
in: query
name: freeForm
type: object
additionalProperties:
type: integer
style: form
```

#### <a name="requestBodyObject"></a>Request Body Object

Describes a single request body.
Expand Down Expand Up @@ -1176,7 +1200,7 @@ requestBody:
Note that in the above example, the contents in the `requestBody` must be stringified per RFC1866 when being passed to the server. In addition, the `address` field complex object will be strigified as well.

When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `deepObject`.
When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `form`.

##### Special Considerations for `mutlipart` content

Expand Down Expand Up @@ -1239,10 +1263,10 @@ A single encoding definition applied to a single schema property
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="contentType"></a>contentType | `string` | **Required.** The content-type to use for encoding a specific property.
<a name="headers"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
<a name="style"></a>Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property
<a name="explode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. The default value is false.
<a name="encodingContentType"></a>contentType | `string` | The content-type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` - `application/octet-stream`; for other primitive types - `plain/text`; for `object` - `application/json`; for `array` - the default is defined based on the inner type.
<a name="encodingHeaders"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
<a name="encodingStyle"></a>style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
<a name="encodingExplode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.

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

Expand Down

0 comments on commit d78e003

Please sign in to comment.