Merge pull request #3860 from handrews/path-item-ref-311

Path Item $ref change warning (3.1.1)

Author: ralfhandl

versions/3.1.1.md

@@ -840,7 +840,7 @@ The path itself is still exposed to the documentation viewer but they will not k
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="pathItemRef"></a>$ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and 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). <br><br>**Deprecated:** Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`.
+<a name="pathItemRef"></a>$ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and 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). <br><br>_**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)._
 <a name="pathItemSummary"></a>summary| `string` | An optional string summary, intended to apply to all operations in this path.
 <a name="pathItemDescription"></a>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.
 <a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.