diff --git a/versions/4.0.0.md b/versions/4.0.0.md index 7c4d640c0e..7394e062c2 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. @@ -17,10 +17,12 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) + - [OpenAPI Fragment Document](#oasFragment) + - [OpenAPI Library Document](#oasLibrary) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) -- [Specification](#specification) +- [OAS Document Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) @@ -58,8 +60,18 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) +- [OAS Fragment Document Specification](#fragment) + - [Versions](#fragmentVersions) + - [OAS Fragment Document Type](#fragmentDocumentType) + - [Schema](#fragmentSchema) + - [OpenAPI Fragment Object](#fragmentObject) + - [Fragment Components Object](#fragmentComponents) +- [OAS Library Document Specification](#library) + - [Versions](#libraryVersions) + - [OAS Library Document Type](#libraryDocumentType) + - [Schema](#librarySchema) + - [OpenAPI Fragment Object](#libraryObject) - [Appendix A: Revision History](#revisionHistory) @@ -70,6 +82,12 @@ An OpenAPI definition can then be used by documentation generation tools to disp ##### OpenAPI Document A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. +##### OpenAPI Fragment Document +A document defines or describes a reusable OpenAPI component that can be referenced from multiple OpenAPI documents. + +##### OpenAPI Library Document +A document defines or describes multiple reusable OpenAPI components that can be referenced from multiple OpenAPI documents. + ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -3364,6 +3382,153 @@ 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 Fragment Document Specification + +### Versions + +OAS Fragment documents, in the same way as the 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. + +The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. + +Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. + +An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) 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 Fragment Document Type + +OAS Fragment documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Fragment"`. + +### 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 Fragment Object + +This is the root document object for a [OpenAPI Fragment Object](#fragmentObject) + + +##### 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 Fragment`] value identifying the fragment document +description | string | Description of the fragment usage +components | [Fragment Components Object](#fragmentComponentsObject) | An element to hold the schema for the fragment component + +##### OpenAPI Fragment Object Example + +A fragment for an schema can be described as: + +``` yaml +openapi: 4.0.0 +openapi-document: OAS Fragment +description: Schema fragment describing an account with code and balance +components: + schemas: + Account: + type: object + properties: + code: + type: string + balance: + type: number +``` + +#### Fragment Components Object + +OAS Fragment documents encode the information about a single component that can be re-used across multiple documents. The components object for a fragment is equivalent to the ['Components Object'](#componentsObject) of the main OAS Document but only one component can be encoded + +##### Fixed Fields + +Only one component key and value are allowed in OpenAPI Fragments + +Field Name | Type | Description +---|:---|--- + schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | 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). + 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). + callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +## OAS Library Document Specification + +### Versions + +OAS Library documents, in the same way as the 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. + +The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. + +Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. + +An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) 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 Library Document Type + +OAS Fragment documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Library"`. + +### 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 Library Object + +This is the root document object for a [OpenAPI Library Object](#libraryObject) + + +##### 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 Library`] value identifying the library document +description | string | Description of the library usage +components | [Fragment Components Object](#componentsObject) | An element to hold the schema for the library components + +##### OpenAPI Library Object Example + +A library with multiple components can be described as: + +``` yaml +openapi: 4.0.0 +openapi-document: OAS Fragment +description: Library with some shared components +components: + schemas: + User: + type: object + properties: + name: + type: string + age: + type: number + format: int32 + Account: + type: object + properties: + code: + type: string + balance: + type: number + parameters: + freeTextSearch: + name: search + in: query + description: free text search value + required: false + schema: + type: string + +``` + ## Appendix A: Revision History Version | Date | Notes