Path item $refs override inline operations instead of merging

[hkosova]

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 OAI/OpenAPI-Specification#1038 (comment), 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.

[gouthams]

@webron @hkosova Looks like this is open for a long time. Is there any resolution?

[Skeeve]

I think this can be closed. According to https://swagger.io/docs/specification/using-ref/#sibling the observed behavior is as described.

[hkosova]

@Skeeve

I think this can be closed. According to https://swagger.io/docs/specification/using-ref/#sibling the observed behavior is as described.

No, this is an actual issue. Path items $refs are different from other $refs in that they are supposed to be merged with siblings.

[Skeeve]

@hkosova

No, this is an actual issue. Path items $refs are different from other $refs in that they are supposed to be merged with siblings.

Okay… Didn't know that.

Tbh. I came here because I thought a merge or overwrite would be helpful in other places too.

See: https://gist.github.com/Skeeve/4d0b41626bdaa82ea1a12d2e4bbd7b55

I have in my schema different sets of required properties. With the posibillity to merge, this could be handled. As far as I know I have to duplicate what's defined in the schema in order to be able to achieve the case of different required properties.

[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]

the workaround to add extra properties to a schema $ref is to wrap the $ref into allOf.

Thanks again @hkosova, but I seem to not understand how to do that. Swagger Editor keeps complaining about structural errors.

Maybe you can give me a hint?

This is what I currently think I would have to have because of not understanding how to properly achieve it:

openapi: 3.0.2
paths:
  /manage/client:
    post:
      summary: Create a new Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_Client'
    put:
      summary: Modify a Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modify_Client'
components:
  schemas:
    create_Client:
      title: Clientdata
      type: object
      required:
      - client_id
      - client_name
      - complaint_address
      properties:
        client_id:
          type: string
        client_name:
          type: string
        complaint_address:
          type: string
          format: email
        fbl_address:
          type: string
          format: email
        status:
          type: string
          pattern: ^(standard|partner|prospect|suspended|delisted|deleted)$
    modify_Client:
      title: Clientdata
      type: object
      properties:
        client_id:
          type: string
        client_name:
          type: string
        complaint_address:
          type: string
          format: email
        fbl_address:
          type: string
          format: email
        status:
          type: string
          pattern: ^(standard|partner|prospect|suspended|delisted|deleted)$

You see: The modify_Client schema only differs from the create_Client in regards to the "requiredness" of properties.

[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'