From 0ba734332b4f253adfd3355f829941d292947beb Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Tue, 18 Dec 2018 23:00:13 +0000 Subject: [PATCH 1/6] Make paths object optional --- versions/3.1.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index f0c7f54abe..8adfc96b4f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -193,7 +193,7 @@ 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. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. -paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. +paths | [Paths Object](#pathsObject) | The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. 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. @@ -647,7 +647,7 @@ components: #### Paths Object Holds the relative paths to the individual endpoints and their operations. -The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). +The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). Paths MAY be omitted in some classes of OAS documents, including referenced sub-documents and overlays. ##### Patterned Fields @@ -3394,7 +3394,7 @@ While not part of the specification itself, certain libraries MAY choose to allo 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. +1. The [Paths Object](#pathsObject) MAY be present but 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 would 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. ## Appendix A: Revision History From efaf094da5039afde921d040b2bbf07843edfc17 Mon Sep 17 00:00:00 2001 From: Ron Date: Wed, 22 Jan 2020 17:43:32 -0700 Subject: [PATCH 2/6] Adding reusable Path Item Objects Under `components` --- versions/3.1.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 4fde92a26e..39ac5a9002 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -458,6 +458,8 @@ Field Name | Type | Description 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). + pathitems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject). + This object MAY be extended with [Specification Extensions](#specificationExtensions). From 4836cce9c8a75d6d295e9ab042cda8fb19bb8993 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 30 Jan 2020 16:10:56 +0000 Subject: [PATCH 3/6] Adopt DM's suggested change to OpenAPI doc definition --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 39ac5a9002..5fa81589c8 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -68,7 +68,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Document -A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. +A document (or set of documents) that defines or describes an API or elements of an API. The document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. From bfcaa37537cdcc23f63c44da86e8ba96f6c8e0fb Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 30 Jan 2020 16:52:49 +0000 Subject: [PATCH 4/6] Cleanup use of specification and definition where we mean document --- versions/3.1.0.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 5fa81589c8..b3d01f8512 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -68,7 +68,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Document -A document (or set of documents) that defines or describes an API or elements of an API. The document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI definition uses and conforms to the OpenAPI Specification. +A self-contained or multipartite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -183,7 +183,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Object -This is the root document object of the [OpenAPI document](#oasDocument). +This is the root object of the [OpenAPI document](#oasDocument). ##### Fixed Fields @@ -194,9 +194,9 @@ Field Name | Type | Description servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | The available paths and operations for the API. webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. +components | [Components Object](#componentsObject) | An element to hold various schemas for the document. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. -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. +tags | [[Tag Object](#tagObject)] | A list of tags used by the document 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. @@ -1643,10 +1643,11 @@ The documentation is not necessarily expected to cover all possible HTTP respons However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes -that are not covered individually by the specification. +that are not covered individually by the `Responses Object`. -The `Responses Object` MUST contain at least one response code, and it -SHOULD be the response for a successful operation call. +The `Responses Object` MUST contain at least one response code, and if only one +response code is provided it SHOULD be the response for a successful operation +call. ##### Fixed Fields Field Name | Type | Description @@ -2047,7 +2048,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred -for specifications with external references. +for OpenAPI documents with external references. ##### Examples @@ -2243,7 +2244,7 @@ description: Pets operations #### Reference Object -A simple object to allow referencing other components in the specification, internally and externally. +A simple object to allow referencing other components in the OpenAPI document, internally and externally. The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. @@ -2673,7 +2674,7 @@ components: #### Discriminator Object -When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. +When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. @@ -3392,7 +3393,7 @@ While not part of the specification itself, certain libraries MAY choose to allo Two examples of this: -1. The [Paths Object](#pathsObject) MAY be present but 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 would still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. +1. The [Paths Object](#pathsObject) MAY be present but 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 would still have access to at least 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. ## Appendix A: Revision History From 4754b940e5b746c9a003c012314e64d3527ba93e Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 14 Feb 2020 16:29:11 +0000 Subject: [PATCH 5/6] multipartite>composite, define ACL --- versions/3.1.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index b3d01f8512..1d28c075c8 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -68,7 +68,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Document -A self-contained or multipartite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification. +A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -458,7 +458,7 @@ Field Name | Type | Description 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). - pathitems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject). + pathItems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -653,7 +653,7 @@ components: #### Paths Object Holds the relative paths to the individual endpoints and their operations. -The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). Paths MAY be omitted in some classes of OAS documents, including referenced sub-documents and overlays. +The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering). Paths MAY be omitted in some classes of OAS documents, including referenced sub-documents and overlays. ##### Patterned Fields From 90736292af99db8eabbadb74b33b0424853ae192 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Wed, 19 Feb 2020 08:48:43 +0000 Subject: [PATCH 6/6] Add ' | Reference Object' to callbacks/webhooks --- versions/3.1.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 1d28c075c8..4b9bd900d5 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -193,7 +193,7 @@ Field Name | Type | Description info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | The available paths and operations for the API. -webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. +webhooks | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. components | [Components Object](#componentsObject) | An element to hold various schemas for the document. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the document 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. @@ -1854,7 +1854,7 @@ To describe incoming requests from the API provider independent from another API ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. +{expression} | [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject) | A Path Item Object, or a reference to one, used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. This object MAY be extended with [Specification Extensions](#specificationExtensions).