Deprecate Path Item Object ref field (#2635) (#2656)

* Deprecate Path Item Object ref field (#2635)

 The  field has been deprecated in favor of
using Reference Object in OAS 3.2.0 and forward.

Signed-off-by: Vladimir Gorej <[email protected]>

* Deprecate Path Item Object ref field specific usecases

Refs #2635

* fix change

Author: char0n

versions/3.1.1.md

@@ -740,7 +740,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 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).
+<a name="pathItemRef"></a>$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). <br><br>**Deprecated:** Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`.
 <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.