Is it possible to reference a single path and method in OpenAPI 3?

Question

Suppose I have an OpenAPI 3 document describing API Foo as follows:

openapi: 3.0.0
info:
  version: '1'
  title: Foo
paths:
 /foo:
  get:
    responses:
      200:
        description: A Foo
  post:
    responses:
      201:
        description: Foo created

In another OpenAPI document for API Bar, I would like to reference only the GET /foo operation from API Foo. The OpenAPI docs talk a little about referencing a whole path. However, if I do the following:

openapi: 3.0.0
info:
  version: '1'
  title: Bar
paths:
 /foo:
  $ref: 'foo.yaml#/paths/~1foo'

I naturally get both the GET and the POST in API Bar, since only the path is referenced, not the method.

I tried this:

openapi: 3.0.0
info:
  version: '1'
  title: Bar
paths:
 /foo:
   get:
     $ref: 'foo.yaml#/paths/~1foo/get'

But this gives errors like should NOT have additional properties additionalProperty: $ref and should have required property 'responses' missingProperty: responses in various tools, so it doesn't seem to be supported.

Is there a way to accomplish this? I should note that the real request is much more complicated, hence the desire to de-duplicate. If possible I would like to avoid filling in many child objects of get with individual $refs.

Answer 1

OpenAPI doesn't have a way to $ref an individual operation (get/post/etc.), you can only $ref an entire path.

You can propose syntax enhancements in the OpenAPI Specification repository:
https://github.com/OAI/OpenAPI-Specification/issues