Skip to content

Request bodies moved out of parameters #670

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 2 commits into from
Jun 6, 2016
Merged

Request bodies moved out of parameters #670

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b521d6c
Request bodies moved out of parameters
jharmn Apr 25, 2016
f5b4941
Removed path-level body, added required flag for body, other typos an…
jharmn May 6, 2016
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
162 changes: 95 additions & 67 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ Field Name | Type | Description
<a name="pathItemHost"></a>host | `string` | The host (name or ip) serving the path. This optional value will override the top-level [host](#oasHost) if present. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating).
<a name="pathItemBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#pathItemHost). This optional value will override the top-level [basePath](#oasBasePath) if present. If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating).
<a name="pathItemSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
<a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). There can be one "body" parameter at most.
<a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).

##### Patterned Fields

Expand Down Expand Up @@ -445,7 +445,8 @@ Field Name | Type | Description
<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
<a name="operationConsumes"></a>consumes | [`string`] | A list of MIME types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
<a name="operationProduces"></a>produces | [`string`] | A list of MIME types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). There can be one "body" parameter at most.
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
<a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation.
<a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
<a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition.
<a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
Expand Down Expand Up @@ -595,25 +596,24 @@ Describes a single operation parameter.

A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).

There are six possible parameter types.
There are five possible parameter types.
* Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
* Header - Custom headers that are expected as part of the request.
Copy link
Member

Choose a reason for hiding this comment

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

Removing this description removes the restriction of using body parameters alongside formData parameters (which just can't happen). We either need to add it (probably in both places) or discuss moving formData parameters to the requestBody as well.

* Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
* Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in the OpenAPI Specification's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
* `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@webron to look at how to deal with form urlencoded parameters.

* `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers.

* Cookie - Used to pass a specific cookie value to the API.


For complex parameter schemas, a serialization strategy is required. For parameter of type `in: body`, the serialization will be handled by the `consumes` attribute. For all other types, a serialization strategy must be declared.
For complex parameter schemas, a serialization strategy is required. For all types, a serialization strategy must be declared.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="parameterName"></a>name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.</ul>
<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData", "body", or "cookie".
<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) 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.
Expand All @@ -628,59 +628,6 @@ Field Pattern | Type | Description

##### Parameter Object Examples

###### Body Parameters

A body parameter with a referenced schema definition (normally for a model definition):
```js
{
"name": "user",
"in": "body",
"description": "user to add to the system",
"required": true,
"schema": {
"$ref": "#/definitions/User"
}
}
```

```yaml
name: user
in: body
description: user to add to the system
required: true
schema:
$ref: '#/definitions/User'
```

A body parameter that is an array of string values:
```js
{
"name": "user",
"in": "body",
"description": "user to add to the system",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
```

```yaml
name: user
in: body
description: user to add to the system
required: true
schema:
type: array
items:
type: string
```

###### Other Parameters

A header parameter with an array of 64 bit integer numbers:

```js
Expand Down Expand Up @@ -786,9 +733,88 @@ schema:
type: file
```

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

Describes a single request body.

The `Content-Type` of the request body must be specified by the `consumes` attribute, either at the [top-level](#oasConsumes) or [operation level](#operationConsumes).

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
<a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
Copy link
Member

Choose a reason for hiding this comment

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

Just noticed this - shouldn't the schema field be required? What does a request body mean without a schema?

Copy link
Contributor

Choose a reason for hiding this comment

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

Some of our APIs use AtomPub-style "media resources", see https://tools.ietf.org/html/rfc5023#section-9.6. In this case the request body of a POST can have any media type, e.g. a picture or PDF document, so there's no schema.

Copy link
Member

Choose a reason for hiding this comment

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

Many media types full describe the semantics of a body.

<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by mime type.
<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.


##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
<a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details.


##### Request Body Examples

A request body with a referenced model definition.
```js
{
"description": "user to add to the system",
"schema": {
"$ref": "#/definitions/User"
},
"examples": {
Copy link
Member

Choose a reason for hiding this comment

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

Looks like we can't avoid discussing how examples are written. I don't know what it means to reference an external non-json/yaml file. Also, examples values were intended to be taken as-is, so the $ref is the example in this case. Furthermore (and related to the two points above) - the only real way to represent non-json examples is to quote them as strings, but for JSON many people opt to just using JSON as-is without quoting. This makes processing a bit more difficult.

This is probably out of scope for this PR though and should be handled separately.

"application/json": {
"$ref": 'http://foo.bar#/examples/address-example.json'
'application/xml':
$ref: 'http://foo.bar#/examples/address-example.xml'
'text/plain':
$ref: 'http://foo.bar#/examples/address-example.txt'
default:
$ref: 'http://foo.bar#/examples/address-example.whatever'
}
```

```yaml
description: user to add to the system
schema:
$ref: '#/definitions/User'
examples:
'application/json':
$ref: 'http://foo.bar/examples/user-example.json'
'application/xml':
$ref: 'http://foo.bar/examples/user-example.xml'
'text/plain':
$ref: 'http://foo.bar/examples/user-example.txt'
default:
$ref: 'http://foo.bar/examples/user-example.whatever'
```

A body parameter that is an array of string values:
```js
{
"description": "user to add to the system",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
```

```yaml
description: user to add to the system
required: true
schema:
type: array
items:
type: string
```

#### <a name="itemsObject"></a>Items Object

A limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located [`in`](#parameterIn) `"body"`.
A limited subset of JSON-Schema's items object. It is used by parameter definitions.

##### Fixed Fields
Field Name | Type | Description
Expand Down Expand Up @@ -1060,7 +1086,7 @@ X-Rate-Limit-Reset:

#### <a name="exampleObject"></a>Example Object

Allows sharing examples for operation responses.
Allows sharing examples for operation requests and responses.

##### Patterned Fields
Field Pattern | Type | Description
Expand All @@ -1069,7 +1095,7 @@ Field Pattern | Type | Description

##### Example Object Example

Example response for application/json mimetype of a Pet data type:
Example request or response for application/json mimetype of a Pet data type:

```js
{
Expand Down Expand Up @@ -1173,7 +1199,7 @@ Anywhere an `example` may be given, allow a $ref object. This does mean that `e

In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.

In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.
In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to validate compatibility automatically, and reject the example value(s) if they are not compatible.

```yaml
# in a model
Expand All @@ -1184,10 +1210,8 @@ definitions:
example:
$ref: http://foo.bar#/examples/name-example

# in a parameter, note the plural `examples` as the content-type is set by `consumes`:
parameters:
- name: address
in: body
# in a request body, note the plural `examples` as the content-type is set by `consumes`:
requestBody:
schema:
$ref: '#/definitions/Address'
examples:
Expand All @@ -1199,6 +1223,10 @@ definitions:
$ref: 'http://foo.bar#/examples/address-example.txt'
default:
$ref: 'http://foo.bar#/examples/address-example.whatever'

# in a parameter

parameters:
- name: 'zip'
in: 'query'
type: 'string'
Expand Down