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 someshared file to be referenced from other APIs. OAS3 supports this using the normal$refkeyword, e.g:
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.
BUTthe external referencestill is not resolved. The screenshot below shows a resolver error on the top right, and the external reference being empty on the bottom right.
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.yamlabove), 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...
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.
2Error 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.
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).