From 3f8a9e3605ce8b0bb1e4d1387b811d998240fb42 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 12:51:46 -0700 Subject: [PATCH 1/2] Path Item $ref change warning (3.1.1) Previously we deprecated the special $ref behavior entirely, but doing so violates the compatibility guidelines that we have re-established for ourselves within 3.x. This wording allows changes in 3.2, but emphasizes convergence rather than discouraging the usage. --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 5563672e57..06579a8227 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -829,7 +829,7 @@ The path itself is still exposed to the documentation viewer but they will not k Field Name | Type | Description ---|:---:|--- -$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form 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. See the rules for resolving [Relative References](#relativeReferencesURI).

**Deprecated:** Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`. +$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form 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. See the rules for resolving [Relative References](#relativeReferencesURI).

_**Note:** The behavior of `$ref` with adjacent properties is likely to change in future versions of this specification to bring it into closer alignment with the behavior of the Reference Object._ 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 ecffb1e297159c03076c922e573ea070175005eb Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 28 May 2024 06:40:22 -0700 Subject: [PATCH 2/2] Make Reference Object a link (review feedback) Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 06579a8227..023053cfe3 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -829,7 +829,7 @@ The path itself is still exposed to the documentation viewer but they will not k Field Name | Type | Description ---|:---:|--- -$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form 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. See the rules for resolving [Relative References](#relativeReferencesURI).

_**Note:** The behavior of `$ref` with adjacent properties is likely to change in future versions of this specification to bring it into closer alignment with the behavior of the Reference Object._ +$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form 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. See the rules for resolving [Relative References](#relativeReferencesURI).

_**Note:** The behavior of `$ref` with adjacent properties is likely to change in future versions of this specification to bring it into closer alignment with the behavior of the [Reference Object](#referenceObject)._ 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.