Search code examples
corsswaggeropenapiswagger-editor

Cannot load external API definition

We are 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

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

  • We start SwaggerEditor 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"

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 editor doesn't actually check if the given definition (in the example above Person) exists - so if I reference some bogus word there is no error shown. Also the interactive Swagger UI part on the right doesn't show the linked type properly... I.e. it doesn't work as it should.

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.

Solution

  • 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 configUrl should 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...

    • http://127.0.0.1:8080/swagger-editor-master/ points to the Swagger Editor, and
    • http://127.0.0.1:8080/foo/bar.yaml points to the spec file we want to reference from whatever we're currently editing in the Swagger Editor.

    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).