Swagger-editor: Suppor references from an external file

Created on 23 Oct 2017 · 7Comments · Source: swagger-api/swagger-editor

| Q | A
| ----------------------------------- | -------
| Bug or feature request? | Feature reques
| Which Swagger/OpenAPI version? | Version 2
| Which Swagger-Editor version? |
| How did you install Swagger-Editor? | with npm
| Which broswer & version? | Firefox
| Which operating system? | Fedora 25

Demonstration API definition

Described in https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec

Configuration (browser query string, constructor, config.yaml)

N/A

Expected Behavior

In case of references external to the main file the additional files should be also interpreted and the references should work.

Current Behavior

No external references followed.

Possible Solution

This could be achieved in two alternative ways:

A zip file is uploaded with all the referred files. The zipfile is then unzipped with its directory structure and interpreted by swagger-editor
All referred files are made available by the uploader and a base url is provided for every upload. Swagger-editor loads the files from the provided url.

I would prefer the first approach, but woudl be very happy with the 2nd also.

Context

I store the definiton files in a Git repo, but not the merged file. Now I need to create a merged file with json-refs and feed that to swagger-tools. This is an extra step in our workflow and makes the autometic rendering of our json files via swagger-editor on the server impossible.

feature

Source

CsatariGergely

Most helpful comment

I don't think Steve confused editor and spec. He may just have been a bit imprecise in wording.

Some facts and their consequences are:

The Swagger 2.0 editor supports a feature (resolving $ref with relative path) that the Swagger 3.0 editor (also when editing swagger 2.0 files) does not support. This downgrading of functionality prevents some users (those with large APIs in multiple files) from using the 3.0 editor on their 2.0 files.
Migrating API definitions from Swagger/OpenAPI 2.0 to OpenAPI 3.0 file format requires a Swagger 3.0 editor. If that editor misses an important feature (resolving $ref with relative path), people for who this feature is important (those with large APIs in multiple files) cannot migrate their API definitions from 2.0 to 3.0 file format.

andy-maier on 6 Feb 2018

👍5

All 7 comments

The Editor is intended to be used with a single file. You can still use references, but they'd have to be fully qualified URLs and not relative ones.

We might implement a way to set a base URL for references, but it won't be soon.

webron on 23 Oct 2017

hkosova on 24 Oct 2017

This worked in Swagger 2.x editor. Why not implement/migrate the same feature to OpenAPI 3.0?

How do we get existing teams to move to 3.0 without resolving all external references?

stevendearborn on 13 Dec 2017

@stevendearborn it sounds like you're confusing the versions of the tool with the versions of the spec.

webron on 13 Dec 2017

I don't think Steve confused editor and spec. He may just have been a bit imprecise in wording.

Some facts and their consequences are:

The Swagger 2.0 editor supports a feature (resolving $ref with relative path) that the Swagger 3.0 editor (also when editing swagger 2.0 files) does not support. This downgrading of functionality prevents some users (those with large APIs in multiple files) from using the 3.0 editor on their 2.0 files.
Migrating API definitions from Swagger/OpenAPI 2.0 to OpenAPI 3.0 file format requires a Swagger 3.0 editor. If that editor misses an important feature (resolving $ref with relative path), people for who this feature is important (those with large APIs in multiple files) cannot migrate their API definitions from 2.0 to 3.0 file format.

andy-maier on 6 Feb 2018

👍5

Nor can people building new APIs in OpenAPI 3.0 use the Swagger Editor to edit them, if we use external references. Swagger UI has no problem with it.