Warning while using operation ref

[conanguyw]

I want ref a single operation of path, but it waring "Missing required property 'responses'"

[webron]

Referencing a single operation is not supported by the spec. You can reference paths that may contain a single path/operation within them.

[webron]

The warning comes as a result of a bug, as references are just not supported there. The Specification is strict about where it allows references, and that's just not one of those places.

[conanguyw]

But ref the 'operation' does work there. According to ‘ref’ specification , this is a legal operation.
https://swagger.io/docs/specification/using-ref/

[webron]

Correct, but references are not supported everywhere in the OpenAPI Specification. For example, you can't reference description either.

[hkosova]

@conanguyw from the doc you linked to:

Places Where $ref Can Be Used
A common misconception is that $ref is allowed anywhere in an OpenAPI specification file. Actually $ref is only allowed in places where the OpenAPI Specification explicitly states that the value may be a reference.

In paths, $ref can only be used to reference an entire path item, but not individual get/post/etc. operations.

paths:
  # This is supported
  /something:
    $ref: './something.yaml'

  # This is NOT supported
  /something-else:
    get:
      $ref: './something.yaml'

[conanguyw]

ok, thanks a lot !!

[hkosova]

But I want just reference single operation，because our api need to show different operation of the same path to different cooperations.

You can use tools like openapi-filter to create filtered versions of your base OpenAPI document that could be presented to different audiences.

[conanguyw]

Ok,I will have a try, thanks a lot!!

[handrews]

Answered (in two different ways), closing.

[conanguyw]

邮件已收到，我会尽快查看。。。