From dd6eb33535f17a207890ba74901c5cabb0b163dc Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 13:39:10 -0700 Subject: [PATCH 01/10] Removed Server Variables Object --- versions/3.0.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index e577a0ad64..8579bc4730 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -35,7 +35,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - - [Server Variables Object](#serverVariablesObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) @@ -330,7 +329,7 @@ Field Name | Type | Description ---|:---:|--- url | `string` | **Required.** A URL to the target host. This URL supports Server Variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -variables | [Server Variables Object](#serverVariablesObject) | An object holding variables for substitution in the URL template. +variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -376,16 +375,6 @@ servers: default: v2 ``` -#### Server Variables Object - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- - {name} | [Server Variable Object](#serverVariableObject) | A variable to be used for substitution in a Server's URL template. - -This object can be extended with [Specification Extensions](#specificationExtensions). - #### Server Variable Object From cd37500687c4b89ed98b2b5b43b7c3059f263fb7 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 13:46:44 -0700 Subject: [PATCH 02/10] Removed Encoding Object Renamed Encoding Property Object to Encoding Object. --- versions/3.0.md | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8579bc4730..23c6046c2a 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -46,7 +46,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Content Object](#contentObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - - [Encoding Property Object](#encodingPropertyObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callbacks Object](#callbacksObject) @@ -1326,7 +1325,7 @@ Field Name | Type | Description schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified in the media type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. -encoding | [Encoding Object](#encodingObject) | Encoding of the media type. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`. +encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1510,12 +1509,18 @@ In scenarios where more control is needed over the Content-Type for `multipart` #### Encoding Object -An object representing multipart region encoding for `requestBody` objects. +A single encoding definition applied to a single schema property. -##### Patterned Fields -Field Pattern | Type | Description +##### Fixed Fields +Field Name | Type | Description ---|:---:|--- -{property} | [Encoding Property Object](#encodingPropertyObject) | The property name to which the special encoding are applied. This field MUST exist in the schema as a property. +contentType | `string` | The Content-Type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. +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` | Describes how a specific property value will be serialized depending on its type . See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values. +explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. +allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. + +This object can be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example @@ -1552,20 +1557,6 @@ requestBody: contentType: image/png, image/jpeg ``` -#### Encoding Property Object - -A single encoding definition applied to a single schema property. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -contentType | `string` | The Content-Type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. -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` | Describes how a specific property value will be serialized depending on its type . See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values. -explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. -allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. - -This object can be extended with [Specification Extensions](#specificationExtensions). #### Responses Object From f774f1df15c78c94d78c38635095fabdc6f282ea Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 14:03:20 -0700 Subject: [PATCH 03/10] Remove Callbacks Object --- versions/3.0.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 23c6046c2a..746c0760a9 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -48,7 +48,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - - [Callbacks Object](#callbacksObject) - [Callback Object](#callbackObject) - [Headers Object](#headersObject) - [Example Object](#exampleObject) @@ -758,7 +757,8 @@ Field Name | Type | Description 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 components/parameters](#componentsParameters). 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 [RFC7231](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. -callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation. +callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. +The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. @@ -1757,19 +1757,6 @@ Response with no return value: description: object created ``` -#### Callbacks Object - -A map of possible out-of band callbacks related to the parent operation. -Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. -The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. - -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- -{name} | [Callback Object](#callbackObject) \| [Reference Object](#referenceObject) | A Callback Object used to define a callback request and expected responses - -This object can be extended with [Specification Extensions](#specificationExtensions). - #### Callback Object A map of possible out-of band callbacks related to the parent operation. From b228c461ff979cc3460b2918e98299ba286712fd Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 15:30:02 -0700 Subject: [PATCH 04/10] Removed Headers Object --- versions/3.0.md | 57 +++---------------------------------------------- 1 file changed, 3 insertions(+), 54 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 746c0760a9..d982efcf06 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -49,7 +49,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - - [Headers Object](#headersObject) - [Example Object](#exampleObject) - [Links Object](#linksObject) - [Link Object](#linkObject) @@ -1637,7 +1636,7 @@ Describes a single response from an API Operation, including design-time, static Field Name | Type | Description ---|:---:|--- description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -headers | [Headers Object](#headersObject) | A list of headers that are sent with the response. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. +headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. content | [Content Object](#contentObject) | An object containing descriptions of potential response payloads. links | [Links Object](#linksObject) | An object representing operations related to the response payload. @@ -1834,56 +1833,6 @@ myWebhook: ``` -#### Headers Object -Lists the headers that can be sent in a response or forwarded via a link. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. - -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- -{name} | [Header Object](#headerObject) \| [Reference Object](#referenceObject) | The name of the property corresponds to the name of the header. The value describes the type of the header. - -##### Headers Object Example - -Rate-limit headers: - -```json -{ - "X-Rate-Limit-Limit": { - "description": "The number of allowed requests in the current period", - "schema": { - "type": "integer" - } - }, - "X-Rate-Limit-Remaining": { - "description": "The number of remaining requests in the current period", - "schema": { - "type": "integer" - } - }, - "X-Rate-Limit-Reset": { - "description": "The number of seconds left in the current period", - "schema": { - "type": "integer" - } - } -} -``` - -```yaml -X-Rate-Limit-Limit: - description: The number of allowed requests in the current period - schema: - type: integer -X-Rate-Limit-Remaining: - description: The number of remaining requests in the current period - schema: - type: integer -X-Rate-Limit-Reset: - description: The number of seconds left in the current period - schema: - type: integer -``` - #### Example Object ##### Fixed Fields @@ -1985,7 +1934,7 @@ Field Name | Type | Description operationRef | `string` | a relative or absolute reference to an OAS operation. This field is mutually exclusive with the `operationId` field, and must point to the fragment of a valid OAS definition. operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `operationRef` field. Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS. parameters | [Link Parameters Object](#linkParametersObject) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. -headers | [Headers Object](#headersObject) | an object representing headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override. +headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. This represents the headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override. description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/). server | [Server Object](#serverObject) | a server object to be used by the target operation. @@ -2419,7 +2368,7 @@ In the above, the link for `UserCommitHistory` points to the operation `getUserC The Header Object follows the structure of the [Parameter Object](#parameterObject), with the following changes: -1. `name` MUST NOT be specified, it is given in the [Headers Object](#headersObject). +1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). From 702f44ab67fd5f364461757c08989357e5100cce Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 15:48:00 -0700 Subject: [PATCH 05/10] Removed Links Object --- versions/3.0.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index d982efcf06..53a4ad42cc 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -50,7 +50,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - - [Links Object](#linksObject) - [Link Object](#linkObject) - [Link Parameters Object](#linkParametersObject) - [Header Object](#headerObject) @@ -1638,7 +1637,7 @@ Field Name | Type | Description description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. content | [Content Object](#contentObject) | An object containing descriptions of potential response payloads. -links | [Links Object](#linksObject) | An object representing operations related to the response payload. +links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1911,22 +1910,16 @@ schemas: $ref: '#/components/examples/confirmation-success' ``` -#### Links Object -The links object represents a set of possible design-time links for a response. + +#### Link Object + +The `Link object` represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. As opposed to _dynamic_ links (links provided **in** the response payload), the OAS linking mechanism does not require that link information be provided in a specific response format at runtime. For computing links, and providing instructions to execute them, [variable substitution](#variableSubstitution) is used for accessing values in a response and using them as values while invoking the linked operation. -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- - {name} | [Link Object](#linkObject) \| [Reference Object](#referenceObject) | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). The link SHALL reference a single Link Object, or a JSON Reference to a single link object. - -#### Link Object -The `Link Object` is responsible for defining a possible operation based on a single response. - ##### Fixed Fields Field Name | Type | Description From 3711cfe817435e57ae80ed047a7b90edcf3b5967 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 15:55:15 -0700 Subject: [PATCH 06/10] Removed Scopes Object --- versions/3.0.md | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 53a4ad42cc..22b337e6f6 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -60,7 +60,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - - [Scopes Object](#scopesObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) @@ -3388,7 +3387,7 @@ Field Name | Type | Validity | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. +scopes | Map[`string`, `string`] | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3433,31 +3432,6 @@ flows: read:pets: read your pets ``` -#### Scopes Object - -Lists the available scopes for an OAuth2 security scheme. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | `string` | Maps between a name of a scope to a short description of it (as the value of the property). - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Scopes Object Example - -```json -{ - "write:pets": "modify pets in your account", - "read:pets": "read your pets" -} -``` - -```yaml -write:pets: modify pets in your account -read:pets: read your pets -``` #### Security Requirement Object From 53196d5f8263cf8474e2fe47474261150995bb18 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 16:07:06 -0700 Subject: [PATCH 07/10] Removed Link Parameters Object --- versions/3.0.md | 44 ++------------------------------------------ 1 file changed, 2 insertions(+), 42 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 22b337e6f6..e61bbb3402 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -51,7 +51,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - - [Link Parameters Object](#linkParametersObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) @@ -1917,7 +1916,7 @@ The presence of a link does not guarantee the caller's ability to successfully i As opposed to _dynamic_ links (links provided **in** the response payload), the OAS linking mechanism does not require that link information be provided in a specific response format at runtime. -For computing links, and providing instructions to execute them, [variable substitution](#variableSubstitution) is used for accessing values in a response and using them as values while invoking the linked operation. +Many operations require parameters to be passed, and these MAY be dynamic depending on the response itself. For computing links, and providing instructions to execute them, [variable substitution](#variableSubstitution) is used for accessing values in a response and using them as values while invoking the linked operation. ##### Fixed Fields @@ -1925,7 +1924,7 @@ Field Name | Type | Description ---|:---:|--- operationRef | `string` | a relative or absolute reference to an OAS operation. This field is mutually exclusive with the `operationId` field, and must point to the fragment of a valid OAS definition. operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `operationRef` field. Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS. -parameters | [Link Parameters Object](#linkParametersObject) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. +parameters | Map[`string` | Any \| [{expression}](#variableSubstitution) | A map representing parameters to pass to the operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. This represents the headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override. description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/). server | [Server Object](#serverObject) | a server object to be used by the target operation. @@ -2317,45 +2316,6 @@ components: Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. -#### Link Parameters Object -Using the `operationId` to reference an operation in the definition has many benefits, including the ability to define media type options, security requirements, response and error payloads. -Many operations require parameters to be passed, and these MAY be dynamic depending on the response itself. - -To specify parameters required by the operation, we can use a **Link Parameters Object**. -This object contains parameter names along with static or dynamic values: - -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- - {name} | Any \| [{expression}](#variableSubstitution) | A constant value or expression to be evaluated and passed to the linked operation. - -```yaml -paths: - /user/{username}: # ... - /user/{username}/commits: - get: - operationId: userCommitHistory - parameters: - - name: username - in: path - type: string - required: true - - name: page - type: integer - format: int32 - required: true - responses: { ... } -components: - links: - UserCommitHistory: - operationId: userCommitHistory - parameters: - username: $response.body#/user/username - page: 0 -``` - -In the above, the link for `UserCommitHistory` points to the operation `getUserCommitHistory`, and passes the `username` value from the response payload as well as the static scalar value `0`. - #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject), with the following changes: From d8654ad946b128392c6cb0243c75e9b0fe4307f0 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 May 2017 16:22:58 -0700 Subject: [PATCH 08/10] Removed Content Object --- versions/3.0.md | 110 +++--------------------------------------------- 1 file changed, 6 insertions(+), 104 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index e61bbb3402..99a41d01d2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -43,7 +43,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - - [Content Object](#contentObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) @@ -931,15 +930,14 @@ Field Name | Type | Description example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. -For more complex scenarios a [Content Object](#contentObject) can be used to define the media type and schema of the parameter. +For more complex scenarios the [`content`](#parameterContent) can be used to define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. -When `example` or `examples` are provided in conjunction with the `schema` object, -the example MUST follow the prescribed serialization strategy for the parameter. +When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- -content | [Content Object](#contentObject) | The content of the parameter. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | An map containing the representations for the parameter. The key is the media type and the value is used to describe it. ##### Style Values @@ -1103,7 +1101,7 @@ Describes a single request body. Field Name | Type | Description ---|:---:|--- description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -content | [Content Object](#contentObject) | **Required.** The content of the request body. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **Required.** The content of the request body. The key is the media type and the value is used to describe it. required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. @@ -1216,104 +1214,8 @@ content: ``` -#### Content Object - -Describes a set of supported media types. A Content Object can be used in [Request Body Object](#requestBodyObject), -[Parameter Objects](#parameterObject), [Header Objects](#headerObject), and [Response Objects](#responseObject). - -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- -{mediaType} | [Media Type Object](#mediaTypeObject) | A media type that is supported by this container. The key should be the media type and the value is used to describe it. - -##### Content Examples - -```js -"content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "string" - } - }, - "examples": { - "list": { - "summary": "List of names", - "value" : ["Bob","Diane","Mary","Bill"] - }, - "empty":{ - "summary": "Empty List", - "value": [] - } - } - }, - "application/xml": { - "examples": { - "list": { - "summary": "List of names", - "value": "" - }, - "empty": { - "summary":"Empty", - "value": "" - } - } - }, - "text/plain": { - "examples": { - "list": { - "summary": "List of names", - "value": "Bob,Diane,Mary,Bill" - }, - "empty": { - "summary": "Empty", - "value" : "" - } - } - } -} -``` - -```yaml -content: - 'application/json': - schema: - type: array - items: - type: string - examples: - list: - summary: List of Names - value: - - Bob - - Diane - - Mary - - Bill - empty: - summary: Empty - value: {} - - 'application/xml': - examples: - list: - summary: List of names - value: "" - empty: - summmary: Empty list - value: "" - 'text/plain': - examples: - list: - summary: List of names - value: "Bob,Diane,Mary,Bill" - empty: - summary: Empty - value: "" -``` - #### Media Type Object -Each Media Type Object provides schema and examples for a the media type identified by its key. Media Type Objects can be used in a [Content Object](#contentObject). +Each Media Type Object provides schema and examples for a the media type identified by its key. ##### Fixed Fields Field Name | Type | Description @@ -1634,7 +1536,7 @@ Field Name | Type | Description ---|:---:|--- description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. -content | [Content Object](#contentObject) | An object containing descriptions of potential response payloads. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | An map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it. links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). This object can be extended with [Specification Extensions](#specificationExtensions). From 9a1b264a78c61622408e761654fa8c51cec1350f Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 1 Jun 2017 11:52:08 -0700 Subject: [PATCH 09/10] content property --- 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 99a41d01d2..ec0850c978 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -930,7 +930,7 @@ Field Name | Type | Description example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. -For more complex scenarios the [`content`](#parameterContent) can be used to define the media type and schema of the parameter. +For more complex scenarios the [`content`](#parameterContent) property can be used to define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. From 2b61473e472d5b2668771edc39935c6784d2565a Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 1 Jun 2017 12:03:53 -0700 Subject: [PATCH 10/10] callbacks key correction --- 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 ec0850c978..9d7ecbe9c2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -752,7 +752,7 @@ Field Name | Type | Description 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 components/parameters](#componentsParameters). 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 [RFC7231](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. -callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. +callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.