Skip to content

Commit 7d62b8e

Browse files
jharmnjharmn
committed
Revert "Request bodies moved out of parameters"
This reverts commit 4bb62f8.
1 parent 4bb62f8 commit 7d62b8e

File tree

1 file changed

+67
-97
lines changed

1 file changed

+67
-97
lines changed

‎versions/3.0.md

Lines changed: 67 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -346,8 +346,7 @@ Field Name | Type | Description
346346
<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).
347347
<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).
348348
<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.
349-
<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).
350-
<a name="pathItemRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for all the operations described under this path. This request body can be overriden at the operation level, but cannot be removed there.
349+
<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.
351350

352351
##### Patterned Fields
353352

@@ -446,8 +445,7 @@ Field Name | Type | Description
446445
<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.
447446
<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).
448447
<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).
449-
<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).
450-
<a name="operationRequestBody"></a>body | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation. If a request body is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it.
448+
<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.
451449
<a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
452450
<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.
453451
<a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
@@ -597,24 +595,25 @@ Describes a single operation parameter.
597595

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

600-
There are five possible parameter types.
598+
There are six possible parameter types.
601599
* 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`.
602600
* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
603601
* Header - Custom headers that are expected as part of the request.
602+
* 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.
604603
* 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):
605604
* `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.
606605
* `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.
607606

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

610609

611-
For complex parameter schemas, a serialization strategy is required. For all types, a serialization strategy must be declared.
610+
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.
612611

613612
##### Fixed Fields
614613
Field Name | Type | Description
615614
---|:---:|---
616615
<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>
617-
<a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
616+
<a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path", "formData", "body", or "cookie".
618617
<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.
619618
<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`.
620619
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
@@ -629,6 +628,59 @@ Field Pattern | Type | Description
629628

630629
##### Parameter Object Examples
631630

631+
###### Body Parameters
632+
633+
A body parameter with a referenced schema definition (normally for a model definition):
634+
```js
635+
{
636+
"name": "user",
637+
"in": "body",
638+
"description": "user to add to the system",
639+
"required": true,
640+
"schema": {
641+
"$ref": "#/definitions/User"
642+
}
643+
}
644+
```
645+
646+
```yaml
647+
name: user
648+
in: body
649+
description: user to add to the system
650+
required: true
651+
schema:
652+
$ref: '#/definitions/User'
653+
```
654+
655+
A body parameter that is an array of string values:
656+
```js
657+
{
658+
"name": "user",
659+
"in": "body",
660+
"description": "user to add to the system",
661+
"required": true,
662+
"schema": {
663+
"type": "array",
664+
"items": {
665+
"type": "string"
666+
}
667+
}
668+
}
669+
```
670+
671+
```yaml
672+
name: user
673+
in: body
674+
description: user to add to the system
675+
required: true
676+
schema:
677+
type: array
678+
items:
679+
type: string
680+
```
681+
682+
###### Other Parameters
683+
632684
A header parameter with an array of 64 bit integer numbers:
633685

634686
```js
@@ -734,89 +786,9 @@ schema:
734786
type: file
735787
```
736788

737-
#### <a name="requestBodyObject"></a>Request Body Object
738-
739-
Describes a single request body.
740-
741-
If the `requestBody` attribute is not present, or `schema` is not defined, the request body is not required.
742-
743-
The serialization of the request body should be specified by the `consumes` attribute.
744-
745-
##### Fixed Fields
746-
Field Name | Type | Description
747-
---|:---:|---
748-
<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.
749-
<a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
750-
<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by mime type.
751-
752-
753-
##### Patterned Fields
754-
Field Pattern | Type | Description
755-
---|:---:|---
756-
<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.
757-
758-
759-
##### Request Body Examples
760-
761-
A request body with a referenced model definition.
762-
```js
763-
{
764-
"description": "user to add to the system",
765-
"schema": {
766-
"$ref": "#/definitions/User"
767-
},
768-
"examples": {
769-
"application/json": {
770-
"$ref": 'http://foo.bar#/examples/address-example.json'
771-
'application/xml':
772-
$ref: 'http://foo.bar#/examples/address-example.xml'
773-
'text/plain':
774-
$ref: 'http://foo.bar#/examples/address-example.txt'
775-
default:
776-
$ref: 'http://foo.bar#/examples/address-example.whatever'
777-
}
778-
```
779-
780-
```yaml
781-
description: user to add to the system
782-
schema:
783-
$ref: '#/definitions/User'
784-
examples:
785-
'application/json':
786-
$ref: 'http://foo.bar/examples/user-example.json'
787-
'application/xml':
788-
$ref: 'http://foo.bar/examples/user-example.xml'
789-
'text/plain':
790-
$ref: 'http://foo.bar/examples/user-example.txt'
791-
default:
792-
$ref: 'http://foo.bar/examples/user-example.whatever'
793-
```
794-
795-
A body parameter that is an array of string values:
796-
```js
797-
{
798-
"description": "user to add to the system",
799-
"schema": {
800-
"type": "array",
801-
"items": {
802-
"type": "string"
803-
}
804-
}
805-
}
806-
```
807-
808-
```yaml
809-
description: user to add to the system
810-
required: true
811-
schema:
812-
type: array
813-
items:
814-
type: string
815-
```
816-
817789
#### <a name="itemsObject"></a>Items Object
818790

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

821793
##### Fixed Fields
822794
Field Name | Type | Description
@@ -1088,7 +1060,7 @@ X-Rate-Limit-Reset:
10881060

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

1091-
Allows sharing examples for operation requests and responses.
1063+
Allows sharing examples for operation responses.
10921064

10931065
##### Patterned Fields
10941066
Field Pattern | Type | Description
@@ -1097,7 +1069,7 @@ Field Pattern | Type | Description
10971069

10981070
##### Example Object Example
10991071

1100-
Example request or response for application/json mimetype of a Pet data type:
1072+
Example response for application/json mimetype of a Pet data type:
11011073

11021074
```js
11031075
{
@@ -1201,7 +1173,7 @@ Anywhere an `example` may be given, allow a $ref object. This does mean that `e
12011173

12021174
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.
12031175

1204-
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.
1176+
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.
12051177

12061178
```yaml
12071179
# in a model
@@ -1212,8 +1184,10 @@ definitions:
12121184
example:
12131185
$ref: http://foo.bar#/examples/name-example
12141186
1215-
# in a request body, note the plural `examples` as the content-type is set by `consumes`:
1216-
requestBody:
1187+
# in a parameter, note the plural `examples` as the content-type is set by `consumes`:
1188+
parameters:
1189+
- name: address
1190+
in: body
12171191
schema:
12181192
$ref: '#/definitions/Address'
12191193
examples:
@@ -1225,10 +1199,6 @@ definitions:
12251199
$ref: 'http://foo.bar#/examples/address-example.txt'
12261200
default:
12271201
$ref: 'http://foo.bar#/examples/address-example.whatever'
1228-
1229-
# in a parameter
1230-
1231-
parameters:
12321202
- name: 'zip'
12331203
in: 'query'
12341204
type: 'string'

0 commit comments

Comments
 (0)