diff --git a/versions/3.0.md b/versions/3.0.md index 622df7cd33..ecd1f9d441 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -346,7 +346,7 @@ Field Name | Type | Description 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). 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). 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. -parameters | [[Parameter Object](#parameterObject) | [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. +parameters | [[Parameter Object](#parameterObject) | [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 @@ -445,7 +445,8 @@ Field Name | Type | Description 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. 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). 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). -parameters | [[Parameter Object](#parameterObject) | [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. +parameters | [[Parameter Object](#parameterObject) | [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). +requestBody | [[Request Body Object](#requestBodyObject) | [Reference Object](#referenceObject)] | The request body applicable for this operation. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. 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. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. @@ -595,11 +596,10 @@ 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. -* 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. * `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. @@ -607,13 +607,13 @@ There are six possible parameter types. * 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 ---|:---:|--- name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. -in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData", "body", or "cookie". +in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie". 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. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage. @@ -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 @@ -786,9 +733,88 @@ schema: type: file ``` +#### 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 +---|:---:|--- +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. +schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. +examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by mime type. +required | `boolean` | Determines if the request body is required in the request. Defaults to `true`. + + +##### Patterned Fields +Field Pattern | Type | Description +---|:---:|--- +^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": { + "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 +``` + #### 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 @@ -1060,7 +1086,7 @@ X-Rate-Limit-Reset: #### Example Object -Allows sharing examples for operation responses. +Allows sharing examples for operation requests and responses. ##### Patterned Fields Field Pattern | Type | Description @@ -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 { @@ -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 @@ -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: @@ -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'