updated #761 for naming consistency #798

fehguy · 2016-09-29T06:21:26Z

This is a follow-up PR for #761, which fixes #721. The representations element has been added, along with support for multiple examples throughout the schema object. In addition, the request body examples from #670 has been added to the PR.

fehguy · 2016-09-29T06:21:36Z

@OAI/tdc please review

darrelmiller · 2016-09-29T14:32:43Z

@fehguy I'm confused. I had made these changes in #761 but in my last update I had renamed representations to content. Did my changes get merged into yours, or did you have to redo what I had done?

fehguy · 2016-09-29T14:42:18Z

Oh weird, I looked at your commit but I see the word content instead of representations throughout it. Maybe you didn't push your update? Happy to use yours :)

DavidBiesack · 2016-09-29T13:27:23Z

versions/3.0.md

-        type: array
-        items:
-          $ref: '#/definitions/Pet'
+      representations:


text/html was in the (removed) produces; please show how text/html (and other non-JSON responses) are coded with representations

DavidBiesack · 2016-09-29T13:41:13Z

versions/3.0.md

@@ -466,8 +470,6 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <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="operationConsumes"></a>consumes | [`string`] | A list of media 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 [Media Types](#mediaTypes).


consumes was removed from the operation, but representations was not added as a fixed field to the Request Body Object. Should Request Body Object use a fixed field for representations? The corresponding Request Body Examples lists a "representations" item. (This will help solve some, but not all, deficiencies in OpenAPI for overloading operations.)

I'm fixing that.

DavidBiesack · 2016-09-29T13:51:13Z

versions/3.0.md

@@ -466,8 +470,6 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <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="operationConsumes"></a>consumes | [`string`] | A list of media 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 [Media Types](#mediaTypes).
-<a name="operationProduces"></a>produces | [`string`] | A list of media 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 [Media Types](#mediaTypes).


produces was removed from the operation, but representations was not added as a fixed field to the Response Object. Should Response Object use a fixed field for representations? The corresponding Response Object Examples lists a "representations" item.

DavidBiesack · 2016-09-29T13:59:20Z

versions/3.0.md

@@ -466,8 +470,6 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <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="operationConsumes"></a>consumes | [`string`] | A list of media 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 [Media Types](#mediaTypes).
-<a name="operationProduces"></a>produces | [`string`] | A list of media 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 [Media Types](#mediaTypes).


I'm confused by the use of * for a patterned object for the schema object, when this used to be a fixed field schema in 2.0. I don't know how to interpret * here. Does this mean any key string is allowed and it maps to a schema? This should have an example. (As per my comment above - replace this patterned response with a representations object?)

DavidBiesack · 2016-09-29T14:05:43Z

versions/3.0.md

@@ -128,8 +128,6 @@ Field Name | Type | Description
 <a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
 <a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
-<a name="oasConsumes"></a>consumes | [`string`] | A list of media types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes).


For incompatible changes to OAS from 2.0 to 3.0, we need a guide (separate from the spec) on how to convert (or interpret). I.e. if consumes/produces are removed here, how does one transform a 2.0 document to 3.0 and preserve the same API definition? This also applies to removing consumes/produces on an operation. It's only slightly clearer there, since the representations exist, but there are still some ambiguities: if produces lists more than one media type, which one is mapped to the 2xx response bodies, and what happens to the others? Example 2: how are the top level consumes/produces merged with the operation consumes/produces to yield the same effective representations in request and response bodies?

Yes, this is going to be a bit of a challenge. I think the only safe option is to project the mediatypes defined in produces and consumes down into the requestBody and responseObjects and create representation/content objects for each media-type. This could cause some unfortunate bloat in some specs. It is my understanding that operation level 'produces/consumes' overrides higher level declarations.

@DavidBiesack the docs + migration information will come later. It doesn't make sense to do it right now until we're done with all structural changes.

DavidBiesack · 2016-09-29T14:41:11Z

versions/3.0.md

-    "type": "array",
-    "items": {
-      "type": "string"
+  "representations": {


The use of a JSON array schema with text/plain is confusing. If it is an array of strings, it should be application/json. if it is a text (i.e. one user per line) then it is not an array. (Repeated in the YAML example.)

DavidBiesack · 2016-09-29T14:41:34Z

versions/3.0.md

+      $ref: 'http://foo.bar/examples/user-example.xml'
+  '*':
+    schema:
+      $ref: 'http://foo.bar/examples/user-example.whatever'
 ```

 A body parameter that is an array of string values:


This is no longer a "body parameter" but a "request body"

DavidBiesack · 2016-09-29T14:46:30Z

versions/3.0.md

@@ -926,26 +934,34 @@ It can be used to cover undeclared responses.
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="responsesCode"></a>{[HTTP Status Code](#httpCodes)} | [Response Object](#responseObject) <span>&#124;</span> [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code.  [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field must quoted for compatibility between JSON and YAML (i.e. "200"), and may contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`.
+<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) <span>&#124;</span> [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code.  [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field must quoted for compatibility between JSON and YAML (i.e. "200"), and may contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`.


I know the XX wildcard was added previously, but are there (or should there be) constraints on the use of X? I.e. certainly 2XX and 4XX make sense; but do 2X0 or XX0 make sense? Should we limit this to just 1XX, 2XX. 3XX, 4XX, 5XX?

DavidBiesack · 2016-09-29T14:53:28Z

versions/3.0.md

@@ -1649,19 +1702,15 @@ definitions:
      example:
        $ref: http://foo.bar#/examples/name-example

-# in a request body, note the plural `examples` as the content-type is set by `consumes`:
+# in a request body, note the plural `examples` as the content-type is set to `*`:


Use Content-Type not content-type

DavidBiesack · 2016-09-29T14:53:35Z

versions/3.0.md

@@ -1649,19 +1702,15 @@ definitions:
      example:
        $ref: http://foo.bar#/examples/name-example

-# in a request body, note the plural `examples` as the content-type is set by `consumes`:
+# in a request body, note the plural `examples` as the content-type is set to `*`:


I'm unclear on "is set to *" as the example uses application/json. Also, this does not set the Content-Type, it only matches it.

DavidBiesack · 2016-09-29T19:17:22Z

already merged -- is there another PR for some of the changes being worked on? (sorry if I'm not allowing time to actually create the PR!)

Can representations (or the content objects if that is the correct name?) be defined in components and reused with $ref? I don't see any examples that show this such as $ref: '#/components/representations/pet' $ref: '#/components/content/pet'

FWIW, I prefer representations over content; that is literally half of REST after all 😏 . But I admit it is unfortunatly 114% longer

darrelmiller · 2016-09-29T19:30:58Z

@DavidBiesack I merged both Tony's PR and my original PR in. We have the Callbacks PR to merge in and I need to create a PR for the changes to support URI Template stuff and because everything is in one file we keep causing ourselves merge conflicts. So, at this point it's probably best to raise issues with links to the main document and we'll tag them with the '3.0 needs documentation' tag.

We can reuse responses, so I'm not sure there is a need for reusing content objects. But I'm open to being convinced otherwise.

Initially I preferred representation, but once I realized that I could describe it as a content object that contains "Content Type" descriptions, and that ties directly to the HTTP header, it felt more natural. Most people are not familiar with the "representations" terminology.

updated OAI#761 for naming consistency

updated #761 for naming consistency

650000a

fehguy added the OpenAPI.Next Proposal label Sep 29, 2016

DavidBiesack suggested changes Sep 29, 2016

View reviewed changes

darrelmiller merged commit 4db3b2d into OpenAPI.next Sep 29, 2016

fehguy deleted the issue-721-alt branch September 29, 2016 17:53

fehguy mentioned this pull request Sep 29, 2016

Support an operation to have multiple specifications per path (e.g. multiple POST operation per path) #182

Closed

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

Merge pull request OAI#798 from OAI/issue-721-alt

32897eb

updated OAI#761 for naming consistency

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

updated #761 for naming consistency #798

updated #761 for naming consistency #798

fehguy commented Sep 29, 2016

fehguy commented Sep 29, 2016

darrelmiller commented Sep 29, 2016

fehguy commented Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016 •

edited

Loading

darrelmiller Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016

darrelmiller Sep 29, 2016

fehguy Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016

DavidBiesack Sep 29, 2016 •

edited

Loading

DavidBiesack Sep 29, 2016 •

edited

Loading

DavidBiesack commented Sep 29, 2016

darrelmiller commented Sep 29, 2016

updated #761 for naming consistency #798

updated #761 for naming consistency #798

Conversation

fehguy commented Sep 29, 2016

fehguy commented Sep 29, 2016

darrelmiller commented Sep 29, 2016

fehguy commented Sep 29, 2016

Choose a reason for hiding this comment

DavidBiesack Sep 29, 2016 • edited Loading

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

DavidBiesack Sep 29, 2016 • edited Loading

Choose a reason for hiding this comment

DavidBiesack Sep 29, 2016 • edited Loading

Choose a reason for hiding this comment

DavidBiesack commented Sep 29, 2016

darrelmiller commented Sep 29, 2016

DavidBiesack Sep 29, 2016 •

edited

Loading

DavidBiesack Sep 29, 2016 •

edited

Loading

DavidBiesack Sep 29, 2016 •

edited

Loading