From 267aaa16709c62fe04778c97034d0c718726011d Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Fri, 28 Jun 2019 09:07:27 +0200 Subject: [PATCH 1/2] 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. --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index b1abb2223a..1c9bbf3a9d 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -732,7 +732,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). A Path Item Object containing a `$ref` property is **not** a [Reference Object](#referenceObject). The properties of the referenced structure are merged with the local Path Item Object. If the same property exists in both, the referenced structure and the local one, this is a conflict. In this case 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 8f97acec421b44f09e34ad1e873eb05d7567d99e Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 18 Feb 2020 10:24:33 -0700 Subject: [PATCH 2/2] Update versions/3.0.3.md --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 1c9bbf3a9d..4eb8bd2956 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -732,7 +732,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). A Path Item Object containing a `$ref` property is **not** a [Reference Object](#referenceObject). The properties of the referenced structure are merged with the local Path Item Object. If the same property exists in both, the referenced structure and the local one, this is a conflict. In this case 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.