Forum Discussion

fgysin's avatar
fgysin
New Contributor
6 years ago

SwaggerEditor: Cannot load external API definition

Hi all, this is my first post and I'm looking for help. :)

My team is using SwaggerEditor to write OAS3 API specifications. Now we'd like to move towards a more organised setup where we move common definitions which are used frequently (e.g. some parameters, errors, object types) to some shared file to be referenced from other APIs. OAS3 supports this using the normal $ref keyword, e.g:

$ref: "http://example.com/shared.yaml#/components/schemas/Person"

What we tried so far

  • I use an absolute URL, i.e. not a relative path.

  • SwaggerEditor is started with the url=... query parameter pointing to our specification file.

    --> The specified URL of the shared API file shows up in the Swagger UI part of the editor (on the right) below the service API title, so this seems to work.

  • The reference I tried to use is to an absolute URL to a YAML file which I host on the same machine as the swagger editor (in an Apache Tomcat). E.g:

    $ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Person"

  • The referenced YAML file was written with SwaggerEditor as well and is compliant OAS3 (i.e. no errors in SwaggerEditor at the time of writing).

I manage to start SwaggerEditor without a CORS error (this seems common while googling this issue and also happened to us first). I can verify in the browser console:

  • The external YAML file is actually sent with the needed CORS header (Access-Control-... *)
  • There are no other errors in the browser console.

BUT the external reference still is not resolved. The screenshot below shows a resolver error on the top right, and the external reference being empty on the bottom right. :robotsad:

What's funny is that the resolver error in the top right disappears once I start editing the yaml on the left, and only reappears if I close and re-open the browser (strange).

Not a CORS issue

(At first we ran into this issue also, but solved it now following the steps below.)

  • I made sure to set the corresponding CORS headers in for the shared YAML (bar.yaml above), i.e. set the filter on the Apache Tomcat's web.xml. I verified that a request to the YAML file gets the CORS headers - I am getting...

    Access-Control-Allow-Origin *

  • When opening SwaggerEditor, make sure to clear the browser cache first, as it could be that the browser still has the request to the referenced external YAML file cached and thus remembers the missing CORS header. This can result in SwaggerEditor showing a CORS error1, even though on the server would, in the meantime, serve the referenced resource with the correct header. More details on the error can also be found in the browsers dev console2.

  • After cache clearing my SwaggerEditor correctly loaded the file again, saw the CORS header and stopped throwing the CORS error.

1 This is the error shown by editor.swagger.io:

Errors

Fetch error
Failed to fetch http://127.0.0.1:8080/foo/bar.yaml

Fetch error
Possible cross-origin (CORS) issue? The URL origin (http://127.0.0.1:8080) does not match the page (http://editor.swagger.io). Check the server returns the correct 'Access-Control-Allow-*' headers.

2 Error shown by the browser JS console upon trying to load an API with external reference:

Access to fetch at 'http://127.0.0.1:8080/foo/bar.yaml' from origin 'http://editor.swagger.io' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.
If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
  • fgysin's avatar
    fgysin
    New Contributor
    6 years ago

    I was able to solve our issue finally. We were using the wrong query parameter when calling SwaggerEditor it seems.

    To correctly load (and resolve) the external YAML specification the query parameter configUrlshould be used (not url!). For example:

    http://127.0.0.1:8080/swagger-editor-master/?configUrl=http://127.0.0.1:8080/foo/bar.yaml

    Where...

    Used like this a reference to the external spec, e.g.

    $ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Payment"

    will be properly resolved in the Swagger UI on the right (e.g. in the Schemas section the referenced properties are expandable, etc.). However it seems that the editor doesn't throw an error if an invalid external reference is given (instead the Swagger UI just shows an 'empty' object).