From 64806a8c7a72c6dc392da2503a99aeb551a10e27 Mon Sep 17 00:00:00 2001 From: seiya Date: Sat, 12 Jan 2019 11:33:51 +0900 Subject: [PATCH 01/30] fix typo in Callback Object Signed-off-by: Mike Ralphson --- 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 db2e9b499a..7ac68aaa73 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1844,7 +1844,7 @@ description: object created A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests 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. +The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. To describe incoming requests from the API provider independent from another API call, use the [`webhooks`](#oasWebhooks) field. From 39685b33d22b42bf3c44356c0145a5b3c0997038 Mon Sep 17 00:00:00 2001 From: Adam Leventhal Date: Tue, 6 Aug 2019 05:33:09 -0700 Subject: [PATCH 02/30] retain typo in v3.0.2; fix for v3.0.3 (#1899) Signed-off-by: Mike Ralphson --- 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 7ac68aaa73..ce98f29e52 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -853,7 +853,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 fully 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 (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. 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. 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. +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. 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. From 52c76a705c49f1caa42094c65bf4c445262a7fa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Fri, 14 Feb 2020 17:13:56 +0100 Subject: [PATCH 03/30] Clarify empty Security Requirement Object usage and validity (#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index ce98f29e52..03e1528fd0 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -195,7 +195,7 @@ Field Name | Type | Description paths | [Paths Object](#pathsObject) | **REQUIRED**. 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. -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. +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. To make security optional, an empty security requirement (`{}`) can be included in the array. 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. @@ -855,7 +855,7 @@ Field Name | Type | Description 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. 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. 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. +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. To make security optional, an empty security requirement (`{}`) can be included in the array. 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -3367,6 +3367,32 @@ petstore_auth: - read:pets ``` +###### Optional OAuth2 Security + +Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object: + +```json +{ + "security": [ + {}, + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ] +} +``` + +```yaml +security: + - {} + - petstore_auth: + - write:pets + - read:pets +``` + ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. From 3318c5554e78234c3b3068d3a1f0067ade640f8c Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Tue, 15 Oct 2019 13:13:16 -0700 Subject: [PATCH 04/30] Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson --- 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 03e1528fd0..fcebe4a5f2 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -102,7 +102,7 @@ The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https:/ 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`. +If an OAS definition has its minor version incremented, it MUST still be a valid definition for the new minor version. E.g., if we have a document that is 3.0.2 and we change the version to 3.1.0, then it MUST be a valid 3.1.0 document. 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"`.) From cc2b6bd91e00e2820e007435aa1b6cfb378371ba Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 24 Oct 2019 12:45:01 -0400 Subject: [PATCH 05/30] ted updates Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index fcebe4a5f2..c07c628f70 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -102,7 +102,9 @@ The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https:/ 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. -If an OAS definition has its minor version incremented, it MUST still be a valid definition for the new minor version. E.g., if we have a document that is 3.0.2 and we change the version to 3.1.0, then it MUST be a valid 3.1.0 document. +Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the openapi property to the new minor version. + +For example, a valid OpenAPI 3.0.2 document, upon changing its openapi property to 3.1.0, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility. 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"`.) From 12f4f57fa123451dcc5bea9683b9779cefc6662f Mon Sep 17 00:00:00 2001 From: Patrice Krakow Date: Thu, 5 Dec 2019 14:28:18 +0100 Subject: [PATCH 06/30] Replace 'application' by 'API' within the 'Info Object' definition. (#2004) Signed-off-by: Mike Ralphson --- 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 c07c628f70..2028efee34 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -213,9 +213,9 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi Field Name | Type | Description ---|:---:|--- -title | `string` | **REQUIRED**. The title of the application. -summary | `string` | A short summary of the application. -description | `string` | A verbose explanation of the application. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +title | `string` | **REQUIRED**. The title of the API. +summary | `string` | A short summary of the API. +description | `string` | A short description of the API. [CommonMark syntax](https://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. From 0a15e65623f76b5e56a261cc06d83bd2eee55e87 Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 12 Feb 2020 15:01:24 -0500 Subject: [PATCH 07/30] Path Templating Clarification - proposed fix for #1830. (#1831) * Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 2028efee34..5b055db267 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -71,7 +71,9 @@ An OpenAPI definition can then be used by documentation generation tools to disp A document (or set of documents) that defines or describes an API. 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. +Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. + +Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). ##### Media Types Media type definitions are spread across several resources. @@ -1016,10 +1018,10 @@ There are four possible parameter locations specified by the `in` field: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
-in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie". -description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is "path", this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. +name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
+in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. +description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. From 67fb5c4a35493e540934638805ecadb0e77fef8b Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Wed, 23 Jan 2019 09:15:05 +0000 Subject: [PATCH 08/30] yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson --- 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 5b055db267..67a91df295 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -128,9 +128,9 @@ The schema exposes two types of fields: Fixed fields, which have a declared name Patterned fields MUST have unique names within the containing object. -In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: +In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: -- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://www.yaml.org/spec/1.2/spec.html#id2803231). +- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. From 4a419941bfd2a7fe697a4fb5ae65e62b26404ae3 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 17 Oct 2018 22:47:26 -0400 Subject: [PATCH 09/30] Updated text for OperationRef Signed-off-by: Mike Ralphson --- 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 67a91df295..a85f13c319 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2037,7 +2037,7 @@ For computing links, and providing instructions to execute them, a [runtime expr Field Name | Type | Description ---|:---:|--- -operationRef | `string` | A relative or absolute reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. +operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. parameters | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an 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. The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. From a879287aa43d4dd6d47d28504d423a42631073e4 Mon Sep 17 00:00:00 2001 From: Seiya Date: Sat, 15 Feb 2020 01:24:00 +0900 Subject: [PATCH 10/30] fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson --- 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 a85f13c319..2b42c2e641 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3419,7 +3419,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. -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. +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 from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History From 8f4c279307873c59475d763fc03d9495be7ff7e4 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 23 Nov 2018 00:02:36 +0000 Subject: [PATCH 11/30] Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 2b42c2e641..76297841ed 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2155,18 +2155,26 @@ This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#ca The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax -``` - expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) - source = ( header-reference | query-reference | path-reference | body-reference ) +```abnf + expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) + source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name - body-reference = "body" ["#" fragment] - fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) - name = *( char ) - char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) - token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) -``` + body-reference = "body" ["#" json-pointer ] + json-pointer = *( "/" reference-token ) + reference-token = *( unescaped / escaped ) + unescaped = %x00-2E / %x30-7D / %x7F-10FFFF + ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' + escaped = "~" ( "0" / "1" ) + ; representing '~' and '/', respectively + name = *( CHAR ) + token = 1*tchar + tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / + "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA +``` + +Here, `json-pointer` is taken from [RFC 6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC 7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). The `name` identifier is case-sensitive, whereas `token` is not. From 7a205a1ec32f29aa137575f644c6b4cae58f34d1 Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Tue, 18 Feb 2020 18:26:23 +0100 Subject: [PATCH 12/30] Explain unclear semantics of property `$ref` in Path Item Object (#1964) * Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in https://github.com/OAI/OpenAPI-Specification/issues/1038#issuecomment-295594246 the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.1.0.md Co-authored-by: Ron Signed-off-by: Mike Ralphson --- 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 76297841ed..5d93aabe07 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -740,7 +740,7 @@ The path itself is still exposed to the documentation viewer but they will not k Field Name | Type | Description ---|:---:|--- -$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. +$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. 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](https://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. From 60dc2b299f846361726b778d73a3ad71fd07cd12 Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 11 Feb 2020 17:39:04 -0500 Subject: [PATCH 13/30] Clarify constraints on Security Scheme Object Scheme Property (#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme Signed-off-by: Mike Ralphson --- 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 5d93aabe07..a29aea79d3 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3180,7 +3180,7 @@ Field Name | Type | Applies To | Description description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. -scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). +scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS. From 5e79257c2ef3363a10923fd29fba62a231ebcf5c Mon Sep 17 00:00:00 2001 From: seiya Date: Thu, 10 Jan 2019 22:35:15 +0900 Subject: [PATCH 14/30] fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index a29aea79d3..e55bf1ef7a 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1783,7 +1783,8 @@ Plain text response with headers: "content": { "text/plain": { "schema": { - "type": "string" + "type": "string", + "example": "whoa!" } } }, From e500f9229138e9ce92c3adb2aebcddd28cafd152 Mon Sep 17 00:00:00 2001 From: Ron Date: Wed, 12 Feb 2020 11:06:02 -0700 Subject: [PATCH 15/30] Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson --- 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 e55bf1ef7a..8733da8c04 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -437,8 +437,8 @@ An object representing a Server Variable for server URL template substitution. Field Name | Type | Description ---|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. +enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. +default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values. description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). From ab6a532bb2dd48b282b27b4b308ce9314468cc6f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 11 Feb 2020 15:05:32 -0800 Subject: [PATCH 16/30] Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 8733da8c04..1496b230eb 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -889,17 +889,17 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "application/x-www-form-urlencoded": { "schema": { "type": "object", - "properties": { - "name": { - "description": "Updated name of the pet", - "type": "string" - }, - "status": { - "description": "Updated status of the pet", - "type": "string" - } - }, - "required": ["status"] + "properties": { + "name": { + "description": "Updated name of the pet", + "type": "string" + }, + "status": { + "description": "Updated status of the pet", + "type": "string" + } + }, + "required": ["status"] } } } From 30196cef7a106e86a87288cb7404abff5702d9d1 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 20 Feb 2020 16:53:32 -0700 Subject: [PATCH 17/30] Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Signed-off-by: Mike Ralphson --- 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 1496b230eb..42249e6ee2 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3435,7 +3435,7 @@ Two examples of this: Version | Date | Notes --- | --- | --- 3.1.0 | TBD | TBD -3.0.3 | TBD | Patch release of the OpenAPI Specification 3.0.3 +3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 From 4f3d63c538f68e830d9614283d5176a7f0a48bf6 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Wed, 27 Nov 2019 20:41:57 +0000 Subject: [PATCH 18/30] Update versions/3.1.0.md Co-Authored-By: Darrel Signed-off-by: Mike Ralphson --- 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 42249e6ee2..ee743e0718 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1904,7 +1904,7 @@ $response.header.Location | https://example.org/subscription/1 ##### Callback Object Examples -The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a callback that goes with the subscription operation to enable registering for the callback. +The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. ```yaml myCallback: From 4effc01f244b2cbd5850979d0e1d23b924db2a18 Mon Sep 17 00:00:00 2001 From: Sergej Date: Fri, 21 Dec 2018 07:36:32 +0100 Subject: [PATCH 19/30] Fixed typo Signed-off-by: Mike Ralphson --- 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 ee743e0718..6cc2d3876c 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1073,7 +1073,7 @@ Assume a parameter named `color` has one of the following values: The following table shows examples of rendering differences for each value. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ------------ | ------ | -------- | -------- | --------|------- +----------- | ------ | -------- | -------- | -------- | ------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 @@ -1083,7 +1083,7 @@ form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 -pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 +pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|B\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). From d98d7a038d11152d50c2e32174830f7d10d66ff1 Mon Sep 17 00:00:00 2001 From: seiya Date: Wed, 2 Jan 2019 23:11:10 +0900 Subject: [PATCH 20/30] explicit 'forward slash' Signed-off-by: Mike Ralphson --- 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 6cc2d3876c..be9876d17f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -661,7 +661,7 @@ The path is appended to the URL from the [`Server Object`](#serverObject) in ord Field Pattern | Type | Description ---|:---:|--- -/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. +/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). From c4d646434eb03828debf1a15e3cabc28df711164 Mon Sep 17 00:00:00 2001 From: nasa9084 Date: Tue, 12 Nov 2019 17:56:20 +0900 Subject: [PATCH 21/30] fix #2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson --- 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 be9876d17f..127914c16a 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -836,9 +836,9 @@ parameters: required: true schema: type: array - style: simple items: type: string + style: simple ``` #### Operation Object From d221d97026417009251c569f37f2404b7d83b5ac Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 23 Dec 2019 11:44:53 +0100 Subject: [PATCH 22/30] OpenAPI not Open API Signed-off-by: Mike Ralphson --- 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 127914c16a..1d2b653ed6 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3442,7 +3442,7 @@ Version | Date | Notes 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification -2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative +2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 From 310b65c4cc38c58e4b34d2b69e744559d6a09aaf Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 24 Oct 2019 12:46:58 -0400 Subject: [PATCH 23/30] backticks Signed-off-by: Mike Ralphson --- 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 1d2b653ed6..b1729b60b2 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -104,9 +104,9 @@ The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https:/ 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. -Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the openapi property to the new minor version. +Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the `openapi` property to the new minor version. -For example, a valid OpenAPI 3.0.2 document, upon changing its openapi property to 3.1.0, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility. +For example, a valid OpenAPI 3.0.2 document, upon changing its `openapi` property to `3.1.0`, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility. 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"`.) From 8b31694d1824f56c1105cad521aeb613160a577f Mon Sep 17 00:00:00 2001 From: Erik Wilde Date: Fri, 14 Feb 2020 09:24:19 -0700 Subject: [PATCH 24/30] minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson Co-authored-by: Ron Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson --- 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 b1729b60b2..8d78a9e61c 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2123,7 +2123,7 @@ solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional -value), references MAY also be made through a relative `operationRef`: +field in an [Operation Object](#operationObject)), references MAY also be made through a relative `operationRef`: ```yaml links: From a7b6c76cf2295941efd684c65e37b172d0460270 Mon Sep 17 00:00:00 2001 From: Sergej Date: Fri, 21 Dec 2018 08:01:41 +0100 Subject: [PATCH 25/30] Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson --- 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 8d78a9e61c..0bd85b8ac3 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1083,7 +1083,7 @@ form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 -pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|B\|150 +pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200\|B\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). From 5e2a7d77ebf3aa2d4759df108f74c1843f1f5a17 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 17 Oct 2018 22:27:31 -0400 Subject: [PATCH 26/30] Removed confusing comment Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 0bd85b8ac3..90cdcd482b 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1468,7 +1468,6 @@ A `requestBody` for submitting a file in a `POST` operation may look like the fo requestBody: content: application/octet-stream: - # any media type is accepted, functionally equivalent to `*/*` schema: # a binary file of any type type: string From 996c413349504462cc2ba4f4dca4420dcc1aee2e Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 12 Feb 2020 15:55:48 -0500 Subject: [PATCH 27/30] Clarify the spec to allow optional or unspecified OAuth scopes (#1888) * Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 90cdcd482b..0f7e7ca8f8 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3286,7 +3286,7 @@ Field Name | Type | Applies To | 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. The OAuth2 standard requires the use of TLS. 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. The OAuth2 standard requires the use of TLS. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. -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. +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. The map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -3331,7 +3331,6 @@ flows: read:pets: read your pets ``` - #### Security Requirement Object Lists the required security schemes to execute this operation. @@ -3346,7 +3345,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# Field Pattern | Type | Description ---|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. +{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples From f77f7f591f3cd475a925ad34c8d7c6b1bc072e0b Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 5 Dec 2019 04:03:22 +0000 Subject: [PATCH 28/30] The examples keyword is not supported inside schema (#2042) * examples not supported inside schema * figured it out * a tiny little edit Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 0f7e7ca8f8..019c779d5f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1031,11 +1031,11 @@ For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterSt 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`. +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) | 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. +example | Any | Example of the parameter's potential value. 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` that 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 parameter's potential value. 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` that contains an example, the `examples` value SHALL _override_ the example provided by the schema. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. @@ -1044,7 +1044,7 @@ When `example` or `examples` are provided in conjunction with the `schema` objec Field Name | Type | Description ---|:---:|--- -content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. ##### Style Values @@ -1955,18 +1955,6 @@ validate compatibility automatically, and reject the example value(s) if incompa ##### Example Object Examples -In a model: - -```yaml -schemas: - properties: - name: - type: string - examples: - name: - $ref: https://example.org/petapi-examples/openapi.json#/components/examples/name-example -``` - In a request body: ```yaml @@ -2003,9 +1991,9 @@ parameters: schema: type: 'string' format: 'zip-code' - examples: - zip-example: - $ref: '#/components/examples/zip-example' + examples: + zip-example: + $ref: '#/components/examples/zip-example' ``` In a response: From 4e42746da4e5d1c2a64ab2dc3358cb5cbc86186b Mon Sep 17 00:00:00 2001 From: Patrice Krakow Date: Thu, 5 Dec 2019 04:59:57 +0100 Subject: [PATCH 29/30] Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 019c779d5f..1ab23dcd70 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -3158,7 +3158,8 @@ animals: #### Security Scheme Object Defines a security scheme that can be used by the operations. -Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html). + +Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). Please note that currently (2019) the implicit flow is about to be deprecated [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/id/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE. ##### Fixed Fields From cc50e24203223518d2996ed0c108d33b4ef2317a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 11 Feb 2020 15:05:32 -0800 Subject: [PATCH 30/30] Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson