Support relative references

[pgtelus]

Please add support for relative references to other files. E.g. if I have an API split into multiple files in my working location:

• MyAPI1.yaml
• MyAPI2.yaml
• MyCommonStructures.yaml

... and I want the two API files to relatively refer to the common structures, e.g.:

$ref: MyCommonStructures.yaml#YadaYada

It would be very convenient to be able to work in the editor with these relative references so that user doesn't need to find/create some mechanism to host the files at some absolute location.

Some possible ideas:

• If the user opens/imports a file then use the base path of that location as the relative reference point (this would be most useful for me)
• An editor setting to allow the user to specify the relative base location
• if neither of the above is selected then by default the relative location would be the editor host URL

[dolmen]

When importing a file the editor has no idea of the original location of the file on your filesystem: this is a limit of the browser to protect your files.
Fo a similar reason, the editor which runs at http://editor.swagger.io can not access data on another domain or URI scheme such as file:///...
So this request is not implementable for imported files.

[pgtelus]

What about letting the user specify the relative root location on a local filesystem, can that be done?

[dolmen]

What about letting the user specify the relative root location on a local filesystem, can that be done?

An app running in a browser can't access files on a local filesystem. Game over.

[RodH257]

Could we import the referenced files ourselves? Ie have an 'import references' feature where we select the referenced files and then the editor uses that when it sees a $ref ?

[saharj]

We're using Sway which uses JSON Refs for resolving JSON Pointers. JSON Refs is using Path Loader for loading URLs.

Path loader has PrepareRequestCallback option that allows us to override the request location. With that I thought we can replace the request location based on an option set by Swagger Editor user.
JSON Refs provide relativeBase option which is a shortcut for what I described above

If we override origin and base path for each request in PrepareRequestCallback during resolution of $refs we will have a working remote resolver. Even if a remote JSON Pointer result have another $ref that points to another relative remote JSON Pointer.

Here is an example:

index.swagger.yaml

root:
  $ref: './a.yaml'

a.yaml

a: 
  $ref: '../b.yaml'

b.yaml

foo: bar

Lets say index.swagger.yaml is located at example.com/swaggers/my-swagger/index.swagger.yaml but we're trying to edit it in Swagger Editor, so we copy the contents to Swagger Editor and tell Swagger Editor to resolve all $refs from example.com/swaggers/my-swagger base.

• a.yaml will get requested to editor.swagger.io/a.yaml but we override the base with example.com/swaggers/my-swagger and it resolves fine
• b.yaml will get requested to editor.swagger.io/../a.yaml but we override the base with example.com/swaggers/my-swagger and resolve it to example.com/swaggers/my-swagge/../b.yaml and it will resolve fine as well.

My plan is to add an option to preferences for the base URL of resolving $refs and use that in $ref resolution.

[saharj]

@pgtelus @dolmen @RodH257 please checkout my branch at #1000 and let me know if it works for you.

[saharj]

You can try this feature in http://editor.swagger.io now

[jstephens7]

Is it not possible to import your entire swagger folder to accomplish the same result?

Say you have your swagger folder containing:

• index.swagger.yaml
• a.yaml
• b.yaml

(possibly subdirectories also)

And import that in your swagger editor. Wouldn't that allow you to resolve the references in the same way they are resolved in your application (node for instance)?

[alonbl]

Hi,
Any update on this? I cannot see any option to edit multi-file swagger spec in the editor. Reopen?
Thanks!

[jstephens7]

We decided to just build our swagger file from partials on startup.
We have a _defaults which contains our base objects and we just make a copy for each of our specific set of routes. Each file is a full swagger file so it can be opened standalone in the editor, but on start up we pull in all the routes to a main swagger file which is used by swagger.
E.G.
api/swagger
_defaults.yml (contains shared definitions)
message.yml (contains /message routes and shared definitions)
swagger.yaml (contains /message and /user routes and shared definitions)
user.yml (contains /user routes and shared definitions)

We do the names like this so that we can only watch the .yml files for changes with nodemon and also so that our main swagger.yaml builder ignores the swagger.yaml file itself. Hope this helps.