From 0716d394eaf255a543dee904192e98747540b329 Mon Sep 17 00:00:00 2001 From: Antonio Garrote Date: Mon, 12 Feb 2018 16:09:35 -0800 Subject: [PATCH 1/2] Adding overlays --- versions/4.0.0.md | 328 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 326 insertions(+), 2 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 7c4d640c0e..08d3751528 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -1,6 +1,6 @@ # OpenAPI Specification -#### Version 3.0.1 +#### Version 4.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -20,7 +20,9 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) -- [Specification](#specification) + - [OpenAPI Overlay Documents](#osOverlays) + - [OpenAPI Extension Documents](#oasExtensions) +- [OAS Document Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) @@ -60,6 +62,29 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) +- [OAS Overlay Document Specification](#overlaySpecification) + - [Versions](#overlayVersions) + - [Schema](#overlaySchema) + - [OpenAPI Overlay Object](#oasOverlayObject) + - [Overrides](#overlayOverrides) + - [OpenAPI Object](#oasObjectOverlayExtensions) + - [Info Object](#infoObjectOverlayExtensions) + - [Contact Object](#contactObjectOverlayExtensions) + - [License Object](#licenseObjectOverlayExtensions) + - [Components Object](#componentsObjectOverlayExtensions) + - [Path Item Object](#pathItemObjectOverlayExtensions) + - [Operation Object](#operationObjectOverlayExtensions) + - [External Documentation Object](#externalDocumentationObjectOverlayExtensions) + - [Parameter Object](#parameterDocumentationObjectOverlayExtensions) + - [Request Object](#requestBodyObjectOverlayExtensions) + - [Media Type Object](#mediaTypeObjectOverlayExtensions) + - [Response Object](#responseObjectOverlayExtensions) + - [Example Object](#exampleObjectOverlayExtensions) + - [Link Object](#linkObjectOverlayExtensions) + - [Tag Object](#tagObjectOverlayExtensions) + - [Schema Object](#schemaObjectOverlayExtensions) + - [Security Scheme Object](#securitySchemeObjectOverlayExtensions) +- [OAS Extension Document Specification](#extensionSpecification) - [Appendix A: Revision History](#revisionHistory) @@ -94,6 +119,15 @@ Some examples of possible media type definitions: The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). +##### OpenAPI Overlay Documents +A document containing a partial definition of a valid OpenAPI document that can be applied to an existing OpenAPI document to add implementation details, or provide a translation of human-oriented documentation into different languages, without changing API behavior. +OpenAPI Overlay documents can be part of compositions of multiple OpenAPI Overlay and OpenAPI Extensions documents extending a single OpenAPI document. + +##### OpenAPI Extension Documents +A document containing a partial definition of a valid OpenAPI document that can be applied to an existing OpenAPI document to add behavior or override certain aspects of the functional aspects of an existing OpenAPI document. +OpenAPI Extension documents can be part of compositions of multiple OpenAPI Overlay and OpenAPI Extensions documents extending a single OpenAPI document. + + ## Specification ### Versions @@ -3364,6 +3398,204 @@ Two examples of this: 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see. +## OAS Overlay Document Specification + +### Versions + +OAS Overlay documents, in the same way as standard OAS documents, are versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. + +An OpenAPI Overlay document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasOverlayVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.) + +### OAS Overlay Document Type + +OAS Overlay documents are identified using the required field ['openapi-document-type'](#oasDocumentType) with a value that must match the string `"OAS Overlay"`. + +### Schema + +In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. + +#### OpenAPI Overlay Object + +This is the root document object of the [OpenAPI Overlay document](#oasOverlayObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string +openapi-document | `string` | **REQUIRED**. This string MUST be the [`OAS Overlay`] value identifying the overlay document +extends |[Reference Object](#referenceObject) | **REQUIRED**. Reference to the OAS document or OAS Overlay being overriden +description | string | Description of the overlay usage + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +### Overrides + +OAS Overlay documents provide allow API designer to override non-functional elements in a target OAS document, OAS Overlay document or OAS Extension document. +The following sections define the valid extension points that can be overriden by a OAS extension. + +The algorithm in [Appendix B](#mergingAlgorithm) describes the process implementers of the spec must follow to produce the output document after applying the overlay. + +#### OpenAPI Object + +Field Name | Type | Description +---|:---:|--- +info | [Info Object](#infoObject) | Provides metadata about the API. The metadata MAY be used by tooling as required. +tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Info Object + +Field Name | Type | Description +---|:---:|--- +title | `string` | The title of the application. +description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. +contact | [Contact Object](#contactObject) | The contact information for the exposed API. +license | [License Object](#licenseObject) | The license information for the exposed API. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Contact Object + +Field Name | Type | Description +---|:---:|--- +name | `string` | The identifying name of the contact person/organization. +url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. +email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### License Object + +Field Name | Type | Description +---|:---:|--- +name | `string` | The license name used for the API. +url | `string` | A URL to the license used for the API. MUST be in the format of a URL. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Components Object + +Field Name | Type | Description +---|:---|--- + examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Path Item Object + +Field Name | Type | Description +---|:---:|--- +summary| `string` | An optional, string summary, intended to apply to all operations in this path. +description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Operation Object + +Field Name | Type | Description +---|:---:|--- +tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. +summary | `string` | A short summary of what the operation does. +description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### External Documentation Object + +Field Name | Type | Description +---|:---:|--- +description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +url | `string` | The URL for the target documentation. Value MUST be in the format of a URL. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Parameter Object + +Field Name | Type | Description +---|:---:|--- +description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +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. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Request Body Object + +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/) MAY be used for rich text representation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Media Type Object + +Field Name | Type | Description +---|:---:|--- +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. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Response Object + +Field Name | Type | Description +---|:---:|--- +description | `string` | A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Example Object + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +summary | `string` | Short description for the example. +description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. +externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Link Object + +Field Name | Type | Description +---|:---:|--- +description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Tag Object + +Field Name | Type | Description +---|:---:|--- +description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Schema Object + +Field Name | Type | Description +---|:---:|--- +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. +example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Security Scheme Object + +Field Name | Type | Applies To | Description +---|:---:|---|--- +description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + + ## Appendix A: Revision History Version | Date | Notes @@ -3378,3 +3610,95 @@ Version | Date | Notes 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification + + +## Appendix B: Merging algorithm + +The following algorithm describes the mechanism to merge AST nodes from documents in the specification to produce an output document AST that can be further processed. + +##### Terminology + +**Object & Property** + +_Object_ is a MAP or a SEQUENCE containing MAPPINGS in terms of the underlying AST. + +_Property_ is a MAPPING in terms of YAML, a key and its value pair. + + +**Array** + +_Array_ is a SEQUENCE containing SCALARs or SEQUENCE containing MAPs in terms of the underlying AST + +**Property Types** + +In the merging algorithm, the _Property_ types are referred to as _Property Kind_, which can be one of the following properties highlighted in **bold**: + +**_Object Property_** - a _Property_ having _Object_ as a value. + +**_Array Property_** - a _Property_ having _Array_ of _Objects_ as a value. + +**_Simple property_** - a _Property_ having SCALAR or a SEQUENCE of SCALARS as a value. + +**_Single-value Simple Property_** - a Simple property having SCALAR value. + +**_Multi-value Simple Property_** - a Simple property having a SEQUENCE of SCALARS as value. + +Exceptions: +* Examples are always _Simple Properties_ despite the capability to have complex YAML samples as values. +* Extensions are always _Simple Properties_ despite potentially having a complex node structure. + +**Conflicting Properties** + +Conflicting properties are the properties that cannot coexist in the same Object. + +In the following example, both "type" and "properties" _Properties_ can coexist, but the "enum" _Property_ cannot coexist with both "type" and "properties". + +**The Trees** + +_Master Tree_ - Master file document AST parsing tree result. +_Extension Tree_ - overlay or extension AST parsing tree result. +_Target Tree_ - the result tree. + +**Merging Algorithm:** + +Master document and Extension or Overlay are parsed by YAML parser to produce _Master Tree_ and _Extension Tree_. + +_Master Tree_ and _Extension Tree_ are validated, in case of an error the merge process is cancelled. + +All _includes_ are resolved and applied for both _Master Tree_ and _Extension Tree_. + +All _uses_ are resolved and applied for both _Master Tree_ and _Extension Tree_. The trees MUST NOT have _uses_ instructions with the same namespace referring to different files. + +All Trait and Resource Types applications are applied in the _Master Tree_ + +Initially, _Target Tree_ is made equal to the _Master Tree_. + +**Current Extension Tree Object** is set to the _Extension Tree_ root. +**Current Target Tree Object** is set to the _Target Tree_ root. + +For each **Current Extension Tree Object property** the following is done: + +* If the **property** is an _Ignored Property_, continue to process the next property. +* If the **property** with the same name exists in **Current Target Tree Object**: + * If the **property** and the identically named property in **Current Target Tree Object** have different _Property Kind_: + * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property. + * If the **property** is a _Simple Property_ + * If the **property** is a _Single-value Simple Property_, + * The **property** value in the identically named **Current Target Tree Object** property is replaced with its value from **Current Extension Tree Object** property. + * If the **property** is a _Multi-value Simple Property_ + * The **property** value from **Current Extension Tree Object** property is added to the identically named **Current Target Tree Object** property values if no such value already exists. + * If the **property** is an _Object Property_: + * The same _Merging Algorithm_ is recursively performed for **Current Extension Tree Object** being set to the **property** value, and **Current Target Tree Object** being set to the value of the identically named property in **Current Target Tree Object**. + * If the **property** is an _Array Property_: + * _Objects_ from the property value are added to the identically named **Current Target Tree Object** property value. +* If the **property** with the same name does not exist in **Current Target Tree Object**: + * All _Conflicting Properties_ are removed from the **Current Target Tree Object** + * The **property** is added to the **Current Target Tree Object**. + +_Target Tree_ is validated. + +If the _Extension Tree_ is an Overlay, _Target Tree_ is compared to the _Master Tree_. There MUST NOT be any differences, other than those listed in the "Allowed differences" table in the [OAS Overlay Documents](#overlaySpecification) section. Otherwise the process is cancelled. + +_Target Tree_ has its resource types and Traits applied. + +_Target Tree_ is being serialized to a document or returned as the algorithm output. From 9aff6573ef091b93fbe7d67f833436bff79b5939 Mon Sep 17 00:00:00 2001 From: Antonio Garrote Date: Mon, 12 Feb 2018 16:33:37 -0800 Subject: [PATCH 2/2] Adding extensions --- versions/4.0.0.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 08d3751528..f83d02b7d5 100644 --- a/versions/4.0.0.md +++ b/versions/4.0.0.md @@ -3408,7 +3408,7 @@ An OpenAPI Overlay document compatible with OAS 3.\*.\* contains a required [`op ### OAS Overlay Document Type -OAS Overlay documents are identified using the required field ['openapi-document-type'](#oasDocumentType) with a value that must match the string `"OAS Overlay"`. +OAS Overlay documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Overlay"`. ### Schema @@ -3416,7 +3416,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Overlay Object -This is the root document object of the [OpenAPI Overlay document](#oasOverlayObject). +This is the root document object of the [OpenAPI Overlay Object](#oasOverlayObject). ##### Fixed Fields @@ -3595,6 +3595,35 @@ Field Name | Type | Applies To | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). +### OAS Extension Document Type + +OAS Extension documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Extension"`. + +### Schema + +In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. + +#### OpenAPI Extension Object + +This is the root document object of the [OpenAPI Extension Object](#oasExtensionObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string +openapi-document | `string` | **REQUIRED**. This string MUST be the [`OAS Overlay`] value identifying the overlay document +extends |[Reference Object](#referenceObject) | **REQUIRED**. Reference to the OAS document being overriden +description | string | Description of the extension usage + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +### Overrides + +Unlike OpenAPI Overlays, OpenAPI Extensions are not limited to the non-functional aspects of a OpenAPI Document. Any field in a OpenAPI object can be extended in an overlay as long as the extended value is a syntactically valid object. + +OpenAPI Extensions must be processed according to the algorithm discussed in [Appendix B: Merging Algorithm](#mergingAlgorithm). The resulting output AST must contain a valid OpenAPI Document. + ## Appendix A: Revision History