documented `requestBody` #878

fehguy · 2017-02-01T19:42:58Z

This PR adds documentation for requestBody to describe inputs into operations.

This fixes #665, #303, #222, #418, #179, #874, #800, #303,

It clarifies #430

Danielku15 · 2017-02-01T20:41:20Z

versions/3.0.md

+  type: string
+  format: binary
+
+# mutliple files:


Should be multiple files (spelling)

whitlockjc · 2017-02-01T20:42:44Z

versions/3.0.md

@@ -580,7 +578,7 @@ Field Name | Type | Description
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <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="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="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [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.


What does "is only supported" mean? Does that mean you cannot specify a requestBody in the OAI document in these situations or that the consumer of the OAI document is not required to do anything with the requestBody in these situations? If this is the latter, what impact does this have on tooling authors?

It means the spec does not allow, for example, requestBody on GET operations, and as a tooling vendor, you're outside the spec by supporting it.

Thanks, carry on.

The language needs to be stronger. Should say either that it MUST be one of the specific HTTP verbs (meaning using it with GET, DELETE...) will make the spec invalid - OR - that it SHALL be ignored if used with the wrong verbs (meaning, validation will allow it to exist there, but tools can safely ignore).

whitlockjc · 2017-02-02T18:44:18Z

There are a few places where you use requestBody and I wonder what you think about using a link to the "Request Body Object" documentation itself instead? I see that in the "Content Object" section (https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#content-object) we're already doing this and that's why it came to mind.

webron · 2017-02-02T20:41:10Z

versions/3.0.md

@@ -580,7 +578,7 @@ Field Name | Type | Description
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <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="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="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [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.


The language needs to be stronger. Should say either that it MUST be one of the specific HTTP verbs (meaning using it with GET, DELETE...) will make the spec invalid - OR - that it SHALL be ignored if used with the wrong verbs (meaning, validation will allow it to exist there, but tools can safely ignore).

webron · 2017-02-02T20:42:30Z

versions/3.0.md

+# content transferred with base64 encoding
+schema:
+  type: string
+  format: base64


This is byte today. We can change, but needs to be updated in the other section as well.

this will be a documentation concern

webron · 2017-02-02T20:44:08Z

versions/3.0.md

+  items:
+    type: string
+    format: binary
+```


This is incorrect. You can't have multiple file uploads with octet-stream, as they have no separator. For multiple files, the schema has to be named.

I'm not sure this is true. See http://stackoverflow.com/questions/913626/what-should-a-multipart-http-request-with-multiple-files-look-like

That's multipart. This is octet-stream.

You are right. My bad.

Ron just reminded me that we need to have a property with a name, holding the array property. Thus Ron is right, we can document that an array request body without schema property is meaningless and unsupported by all implementations of the tooling (thx @webron )

webron · 2017-02-02T20:48:05Z

versions/3.0.md

+```
+
+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.
+


Language is okay - this means that a use can choose to define it still, but it will be ignored if not multipart/*.

This should be updated to say the encoding attribute are also applies to application/x-www-form-urlencoded

webron · 2017-02-02T20:53:02Z

versions/3.0.md

+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="encodingObjectProperty"></a>The property to apply encoding to | [Encoding Property](#encodingProperty) <span>&#124;</span> [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-`.


What's Encoding Property? Take a look at the type column.

Would also suggest to reverse the restriction. I think it's better to allow x- in properties and not allow extensions here, as you can add the extensions a level up covering this as well.

I agree that not allowing vendor extensions here would be best.

webron · 2017-02-02T20:54:55Z

versions/3.0.md

+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="contentType"></a>Content-Type | `string` | **Required.** The content-type to use for encoding a specific property.


@webron is wrong. Should stay contentType.

webron · 2017-02-02T21:00:28Z

Thanks for putting this together, @fehguy - this addresses a lot of important issues.

Following our discussions, one thing is missing and that's addressing custom serialization format with x-www-form-urlencoded. The defaults are mentioned. IIRC, these should fall under the Encoding Object.

If we choose to skip that, then the Encoding Object structure can be simplified.

fehguy · 2017-02-03T17:13:12Z

versions/3.0.md

+encoding:
+  historyMetadata:
+    # require XML content-type in utf-8 encoding
+    contentType: application/xml; charset=utf-8


what about Content-Disposition?

Waiting for @darrelmiller for feedback on this

Let's add style here, great idea @webron ?

whitlockjc · 2017-02-03T20:56:22Z

versions/3.0.md

+Field Name | Type | Description
+---|:---:|---
+<a name="contentType"></a>Content-Type | `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.


Is this only applicable for multi-part support? If so, shouldn't we document it as such?

yes it is. I'll address in the PR

webron · 2017-02-03T22:17:50Z

LGTM (though Content-Type should be contentType).

darrelmiller · 2017-02-04T02:09:19Z

versions/3.0.md

+<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="contentType"></a>Content-Type | `string` | **Required.** The content-type to use for encoding a specific property.


Content Type is here twice. Should it even be here or do we move it to headers?

oops. I'll remove one of them.

I left it out of the headers section intentionally. Since it describes the serialization strategy it's (a) required and (b) easier to predict in it's own attribute.

darrelmiller · 2017-02-04T02:11:04Z

LGTM (though see comment about content-type, Ron might be wrong!)

fehguy · 2017-02-07T00:14:50Z

@OAI/tdc shall we merge? (cha cha cha)

whitlockjc · 2017-02-07T00:15:53Z

LGTM

darrelmiller · 2017-02-07T01:10:42Z

documented `requestBody`

documented requestBody

73644ca

fehguy added the OpenAPI.Next Proposal label Feb 1, 2017

removed file type

9cbcaa6

fehguy added a commit that referenced this pull request Feb 1, 2017

fix #878

f51b239

Danielku15 reviewed Feb 1, 2017

View reviewed changes

versions/3.0.md Outdated

type: string

format: binary

# mutliple files:

Copy link

Danielku15 Feb 1, 2017 •

edited

Choose a reason for hiding this comment

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

Should be multiple files (spelling)

whitlockjc reviewed Feb 1, 2017

View reviewed changes

fix spelling

c5380d3

webron reviewed Feb 2, 2017

View reviewed changes

fehguy commented Feb 3, 2017

View reviewed changes

fehguy added 2 commits February 3, 2017 11:09

applied feedback from OAI TDC call

0df060a

applied feedback from OAI TDC call

46c3203

whitlockjc reviewed Feb 3, 2017

View reviewed changes

nitpick fixes

89bb140

darrelmiller reviewed Feb 4, 2017

View reviewed changes

remove duplicate

0abf7f6

fehguy merged commit 17a389a into OpenAPI.next Feb 7, 2017

fehguy deleted the issue-565 branch February 7, 2017 01:13

webron mentioned this pull request Feb 7, 2017

Support for request body with arbitrary Content-Type (OpenAPI.Next) #882

Closed

This was referenced Feb 21, 2017

Keep primitive types within JSON schema draft specs #340

Closed

Improve binary data definitions #430

Closed

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019

fix OAI#878

2e13ffd

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019

Merge pull request OAI#878 from OAI/issue-565

fbbe5b3

documented `requestBody`

		```

		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.

documented requestBody #878

documented requestBody #878

Conversation

fehguy commented Feb 1, 2017 • edited

Danielku15 Feb 1, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fehguy Feb 1, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whitlockjc commented Feb 2, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webron commented Feb 2, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webron commented Feb 3, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

darrelmiller commented Feb 4, 2017

fehguy commented Feb 7, 2017

whitlockjc commented Feb 7, 2017

darrelmiller commented Feb 7, 2017

documented `requestBody` #878

documented `requestBody` #878

fehguy commented Feb 1, 2017 •

edited

Danielku15 Feb 1, 2017 •

edited

fehguy Feb 1, 2017 •

edited

whitlockjc commented Feb 2, 2017 •

edited