From 73644ca2e2bf2134b4e30a4410b5327720721b2c Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Wed, 1 Feb 2017 11:39:07 -0800 Subject: [PATCH 1/7] documented `requestBody` --- versions/3.0.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 180 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 1e9a4f99ef..5d17f63199 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -580,7 +580,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. 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. 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. +requestBody | [[Request Body Object](#requestBodyObject) | [Reference Object](#referenceObject)] | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. @@ -1124,6 +1124,185 @@ application/json: ``` +##### Considerations for file uploads + +In contrast with the 2.0 specification, describing `file` input/output content in OpenAPI is +described with the same semantics as any other schema type. Specifically: + +```yaml +# content transferred with base64 encoding +schema: + type: string + format: base64 + +# content transfered in binary (octet-stream): +schema: + type: string + format: binary + +# mutliple files: +schema: + type: array + items: + type: string + format: binary +``` + +Note that the above examples apply to either input payloads (i.e. file uploads) or response payloads. + + +A `requestBody` example for submitting a file in a `POST` operation therefore may look like the following: + +```yaml +requestBody: + # any media type is accepted, functionally equivalent to `*/*` + application/octet-stream: + content: + schema: + # a binary file of any type + type: string + format: binary +``` + +In addition, specific media types may be specified: + +```yaml +# multiple, specific media types may be specified: +requestBody: + # a binary file of type png or jpeg + content: + 'image/png, image/jpeg': + schema: + type: string + format: binary +``` + +##### Support for x-www-form-urlencoded request bodies + +To submit content using form url encoding via RFC 1866, the following +definition may be used: + +```yaml +requestBody: + content: + x-www-form-urlencoded: + schema: + type: object + properties: + id: + type: string + format: uuid + address: + # complex types are stringified to support rfc1866 + type: object + properties: {} +``` + +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`. + +##### Special Considerations for `mutlipart` content + +It is common to use `multipart/form-data` as a `Content-Type` when transferring request bodies to operations. In contrast to 2.0, a `schema` is required to define the input parameters to the operation when using `multipart` content. This allows complex structures as well as supports mechanisms for multiple file uploads. + +When passing in `multipart` types, boundaries may be used to separate sections of the content being transferred--thus, the following default `Content-Type`s are defined for `multipart/*`: + +* If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` +* If the property is complex, or an array of complex values, the default Content-Type is `application/json` +* If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream` + + +Examples: + +```yaml +requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + id: + type: string + format: uuid + address: + # default Content-Type for objects is `application/json` + type: object + properties: {} + profileImage: + # default Content-Type for string/binary is `application/octet-stream` + type: string + format: binary + children: + # default Content-Type for arrays is based on the `inner` type (text/plain here) + type: array + items: + type: string + addresses: + # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) + type: array + items: + type: '#/definitions/Address' +``` + +In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced. This attribute is _only_ applicable to `mulitpart/*` request bodies. + +#### Encoding Object + +An object representing multipart region encoding for `requestBody` objects + +##### Patterned Fields +Field Pattern | Type | Description +---|:---:|--- +The property to apply encoding to | [Encoding Property](#encodingProperty) | [Encoding](#encoding) | The field name to apply special encoding attributes to. This field must exist in the schema as a property. To avoid collisions with specification extensions, properties may not begin with `x-`. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +#### Encoding + +A single encoding definition applied to a single schema property + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### Encoding Object Examples + +```yaml +requestBody: + content: + multipart/mixed: + schema: + type: object + properties: + id: + # default is text/plain + type: string + format: uuid + address: + # default is application/json + type: object + properties: {} + historyMetadata: + # need to declare XML format! + description: metadata in XML format + type: object + properties: {} + profileImage: + # default is application/octet-stream, need to declare an image type only! + type: string + format: binary +encoding: + historyMetadata: + # require XML content-type in utf-8 encoding + contentType: application/xml; charset=utf-8 + profileImage: + # only accept png/jpeg + contentType: image/png, image/jpeg +``` #### Items Object From 9cbcaa6adfa64dbb2043863005e3a0d919cffe89 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Wed, 1 Feb 2017 11:44:38 -0800 Subject: [PATCH 2/7] removed `file` type --- versions/3.0.md | 28 ++-------------------------- 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 5d17f63199..13dfc58654 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -145,13 +145,11 @@ By convention, the OpenAPI Specification (OAS) file is named `openapi.json` or ` Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft 4](http://json-schema.org/latest/json-schema-core.html#anchor8). Models are described using the [Schema Object](#schemaObject) which is a subset of JSON Schema Draft 4. -An additional primitive data type `"file"` is used by the [Parameter Object](#parameterObject) and the [Response Object](#responseObject) to set the parameter type or the response as being a file. - Primitives have an optional modifier property `format`. OAS uses several known formats to more finely define the data type being used. However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. -Types that are not accompanied by a `format` property follow their definition from the JSON Schema (except for `file` type which is defined above). +Types that are not accompanied by a `format` property follow their definition from the JSON Schema. The formats defined by the OAS are: @@ -742,7 +740,7 @@ There are four possible parameter types. 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" or "cookie". +in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path" or "cookie". 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. 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. @@ -890,28 +888,6 @@ style: form explode: true ``` -A form data with file type for a file upload: -```json -{ - "name": "avatar", - "in": "formData", - "description": "The avatar of the user", - "required": true, - "schema": { - "type": "file" - } -} -``` - -```yaml -name: avatar -in: formData -description: The avatar of the user -required: true -schema: - type: file -``` - #### Request Body Object Describes a single request body. From c5380d36498247cdad0f4192e0b4d0c23f69c8b5 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Wed, 1 Feb 2017 16:04:47 -0800 Subject: [PATCH 3/7] fix spelling --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 13dfc58654..dfa39e66e2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1116,7 +1116,7 @@ schema: type: string format: binary -# mutliple files: +# multiple files: schema: type: array items: From 0df060a4f1ff4cd437b4f3e8ad1655280963901e Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 3 Feb 2017 11:09:35 -0800 Subject: [PATCH 4/7] applied feedback from OAI TDC call --- versions/3.0.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index dfa39e66e2..50a1aee4c9 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -527,7 +527,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "items": { "type": "string" }, - "style": "comma-delimited" + "style": "commaDelimited" } ] } @@ -578,7 +578,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. 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. 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. The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. +requestBody | [[Request Body Object](#requestBodyObject) | [Reference Object](#referenceObject)] | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` shall be ignored by consumers. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. @@ -1115,18 +1115,10 @@ schema: schema: type: string format: binary - -# multiple files: -schema: - type: array - items: - type: string - format: binary ``` Note that the above examples apply to either input payloads (i.e. file uploads) or response payloads. - A `requestBody` example for submitting a file in a `POST` operation therefore may look like the following: ```yaml @@ -1230,9 +1222,7 @@ An object representing multipart region encoding for `requestBody` objects ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -The property to apply encoding to | [Encoding Property](#encodingProperty) | [Encoding](#encoding) | The field name to apply special encoding attributes to. This field must exist in the schema as a property. To avoid collisions with specification extensions, properties may not begin with `x-`. - -This object can be extended with [Specification Extensions](#specificationExtensions). +The property to apply encoding to | [Encoding Property](#encodingProperty) | [Encoding](#encoding) | The field name to apply special encoding attributes to. This field must exist in the schema as a property. #### Encoding @@ -1242,6 +1232,9 @@ A single encoding definition applied to a single schema property Field Name | Type | Description ---|:---:|--- Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. +Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property +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. +Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. This object can be extended with [Specification Extensions](#specificationExtensions). From 46c32035f5e7112c7aef5366032e0c0f9d47f9c4 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 3 Feb 2017 11:13:19 -0800 Subject: [PATCH 5/7] applied feedback from OAI TDC call --- versions/3.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.0.md b/versions/3.0.md index 50a1aee4c9..d222596152 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1232,6 +1232,7 @@ A single encoding definition applied to a single schema property Field Name | Type | Description ---|:---:|--- Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. +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. Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property 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. Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. From 89bb140c3134ccfe526a4121b47bb81bd112acb5 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 3 Feb 2017 15:15:19 -0800 Subject: [PATCH 6/7] nitpick fixes --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index d222596152..11b34d7faf 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1213,7 +1213,7 @@ requestBody: type: '#/definitions/Address' ``` -In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced. This attribute is _only_ applicable to `mulitpart/*` request bodies. +In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced. This attribute is _only_ applicable to `mulitpart/*` and `x-www-form-urlencoded` request bodies. #### Encoding Object @@ -1231,7 +1231,7 @@ A single encoding definition applied to a single schema property ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. +contentType | `string` | **Required.** The content-type to use for encoding a specific property. 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. Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property 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. From 0abf7f619b4cd1659181f6ea915b9c8e5e9e9d69 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Mon, 6 Feb 2017 16:13:32 -0800 Subject: [PATCH 7/7] remove duplicate --- versions/3.0.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 11b34d7faf..0c97e78ea8 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1235,7 +1235,6 @@ Field Name | Type | Description 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. Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property 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. -Content-Type | `string` | **Required.** The content-type to use for encoding a specific property. This object can be extended with [Specification Extensions](#specificationExtensions).