Add support for remote file reference

[skoapptio]

Is there an existing request for this feature?

• [X] I have searched the existing issues for this feature request and I know that duplicates will be closed

Is your feature request related to a problem?

Using the following simple $ref example, it appears that the $ref is not resolved:

File: test.yaml

openapi: 3.0.3
info:
  version: 0.0.0
  title: Simple API
externalDocs:
  description: Find out more about spec
  url: ''
servers: []
tags:
  - name: Default
    description: ''
paths:
  $ref: './paths.yaml'
components:
  schemas: {}
  securitySchemes: {}

File: paths.yaml

/foo
  get:
    responses:
      200:
        description: OK

Describe the solution you'd like

Please add support for breaking a large API spec into smaller files by supporting remote references in $ref. The above example should properly resolve the external reference and effectively result in the following spec:

openapi: 3.0.3
info:
  version: 0.0.0
  title: Simple API
externalDocs:
  description: Find out more about spec
  url: ''
servers: []
tags:
  - name: Default
    description: ''
paths:
  /foo
    get:
      responses:
        200:
          description: OK
components:
  schemas: {}
  securitySchemes: {}

Describe alternatives you've considered

I've considered using internal references, but my API has over a hundred paths and schema objects, so the single-file specification becomes too large to effectively manage.

Additional context

Here is a good write-up on the issue: https://azimi.me/2015/07/16/split-swagger-into-smaller-files.html

[apigitlabs]

Thanks, @skoapptio! While this feature isn't supported right now, it's on our roadmap and expected to be delivered next quarter. Stay tuned for updates!

[MatejJanMoravek]

Hi, I just tried to use this feature and it is still not functional. at least when I try to refer to an object in another file like this: 400BadRequestResponse: $ref: ../../Zakladni-elementy.yaml#/400BadRequestResponse Metadata: $ref: ../../Zakladni-elementy.yaml#/Metadata

I get an error TypeError: r.readFile is not a function and the object I wanted to include is not included. How is it going with this feature?

[apigitlabs]

thanks @MatejJanMoravek , this is still not supported, but we will get it released in some time of Q2/2024

[apigitlabs]

hi @skoapptio , this function is gotten supported in the latest deployment, please have a try.

[apigitlabs]

closed it as it is supported now.