Path item $refs override inline operations instead of merging

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	2.0, 3.0.0
Which Swagger-UI version?	3.2.0
How did you install Swagger-UI?	http://editor.swagger.io
Which browser & version?	Chrome 61
Which operating system?	Windows 7

Demonstration API definition

2.0 spec:

swagger: '2.0'
info:
  version: 0.0.0
  title: Path item $ref test

paths:
  /foo:
    get:
      responses:
        200:
          description: OK

  /foo2:
    $ref: '#/paths/~1foo'
    post:
      summary: Create a foo2
      responses:
        201:
          description: Created

3.0 spec:

openapi: 3.0.0
info:
  version: 0.0.0
  title: Path item $ref test

paths:
  /foo:
    get:
      responses:
        '200':
          description: OK

  /foo2:
    $ref: '#/paths/~1foo'
    post:
      summary: Create a foo2
      responses:
        '201':
          description: Created

Expected Behavior

/foo2 displays both GET (added by $ref) and POST (defined inline).

Current Behavior

/foo2 displays GET only.

Context

According to https://github.com/OAI/OpenAPI-Specification/issues/1038#issuecomment-295594246, when a path item contains a $ref, the referenced operation is added (merged) to other operations in this path. Unlike regular JSON references, path item $refs are not supposed to override their sibling elements.

[hkosova]

@Skeeve the next version of the OpenAPI Specification, 3.1, will support $ref siblings in schemas. Outside of schemas, $refs will allow sibling summary and description keywords. In the meantime, the workaround to add extra properties to a schema $ref is to wrap the $ref into allOf.

[Skeeve]

Hmmm… Could it be, this is correct?

  /manage/client:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                anyOf:
                  $ref: '#/components/schemas/Client/properties'