From 07cf028e5a21cc40598df45df494594302f3b2f7 Mon Sep 17 00:00:00 2001 From: Antonio Garrote Date: Tue, 13 Feb 2018 14:30:17 -0800 Subject: [PATCH] Adding support --- versions/4.0.0.md | 135 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 8 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 7c4d640c0e..084f34a728 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -51,6 +51,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) + - [Merge Object](#mergeObject) + - [Merge Object Spec](#mergeObjectSpec) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) @@ -174,7 +176,7 @@ Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. -Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). +Relative references used in `$ref` an are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). ### Schema @@ -443,11 +445,11 @@ All objects defined within the components object will have no effect on the API Field Name | Type | Description ---|:---|--- - schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). + schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] \| [Merge Object](#mergeObject) | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). - requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). + requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] \| [Merge Object](#mergeObject) | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). @@ -1003,7 +1005,7 @@ Field Name | Type | Description style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. explode | `boolean` | When this is true, parameter 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 parameters this property has no effect. When [`style`](#parameterStyle) 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. This property only applies to parameters with an `in` value of `query`. The default value is `false`. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. +schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | The schema defining the type used for the parameter. example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. @@ -1342,7 +1344,7 @@ Each Media Type Object provides schema and examples for the media type identifie ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. +schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | 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 by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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 SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`. @@ -1621,12 +1623,12 @@ SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#referenceObject) can link to a response that the [OpenAPI Object's components/responses](#componentsResponses) section defines. +default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#referenceObject) can link to a response that the [OpenAPI Object's components/responses](#componentsResponses) section defines. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. +[HTTP Status Code](#httoppCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1682,7 +1684,7 @@ Describes a single response from an API Operation, including design-time, static ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. [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 | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* 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). @@ -2233,6 +2235,123 @@ $ref: Pet.yaml $ref: definitions.yaml#/Pet ``` +#### Merge Object + +A simple object containing the specification to allow merging multiple components in the specification, internally and externally into a single output object combining fields from all of them. + +The Merge Object is defined by [JSON Patch](https://tools.ietf.org/html/rfc6902) and follows the same structure, behavior and rules. + +Notice that merge objects can only be added in the allowed locations in this specification. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +$merge | [Merge Object Spec](#mergeObjectSpec) | **REQUIRED**. The specification of the merge operation. + +This object cannot be extended with additional properties and any properties added SHALL be ignored. + + +#### Merge Object Spec + +Details of the merge operation to be applied to a set components in the specification. + +The Merge Object Spec is defined by [JSON Patch](https://tools.ietf.org/html/rfc6902) and follows the same structure, behavior and rules. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +source | [Request Body Object](#requestBodyObject) \| [Response Object](#responseObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \| [Merge Object](#mergeObject) | **REQUIRED**. The base object used in the merge transformation +with | \[ [Request Body Object](#requestBodyObject) \| [Response Object](#responseObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) \] | **REQUIRED**. The list of objects to be merged on top of the base object + +This object cannot be extended with additional properties and any properties added SHALL be ignored. + + +##### Merge Object Spec Example + +```json +{ + "$merge": { + "source": { + "description": "returns an Account", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Account" } + } + } + }, + "with": [ + { + "headers": { + "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 +$merge: + source: + description: returns an Account + content: + application/json: + schema: + $ref: "#/components/schemas/Account + with: + - headers: + 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 +``` + +##### Relative and absolute references Merge Object Spec example +```json +{ + "$merge": { + "source": { "$ref": "#/components/responses/Accounts" }, + "with": [ + { "$ref": "library.json#/components/responses/rate-limit" } + ] + } +} +``` + +```yaml +$merge: + source: + $ref: "#/components/responses/Accounts" + with: + - $ref: "library.json#/components/responses/rate-limit" +``` + + #### Schema Object The Schema Object allows the definition of input and output data types.