Swagger Editor import vs Swagger UI hosting for restoring an OpenAPI backup with relative $refs

Answer

When you restore a split OpenAPI 3.0 backup into a new folder, the safest way to confirm that every $ref is resolvable is to run a deterministic validation tool first. Swagger‑CLI validate (or a programmatic call to swagger‑parser) guarantees that the spec can be fully resolved without browser quirks. After that, you can use either Swagger Editor or Swagger UI to view the rendered UI, but you should treat the operation list in those tools as a visual aid rather than a definitive proof of correctness.

Why the two browsers differ

• Swagger Editor loads the root file via the local file:// scheme. It resolves $refs against the local file system and will continue to render operations even if some refs cannot be found, often only logging a warning in the console.
• Swagger UI serves the spec over HTTP. It resolves $refs relative to the base URL and enforces same‑origin rules. A missing file will surface as a 404 or a CORS error, making the failure obvious in the UI console.

Recommended verification workflow

1. Run a full validation first:

   npx swagger-cli validate openapi.yaml
   # or
   npx swagger-cli validate --strict openapi.yaml
   

   Any unresolved refs will be listed in the console. The command also produces a fully resolved JSON if you add --output json, which you can compare to the UI’s internal JSON.

2. Inspect the resolved spec programmatically (optional but useful for large specs):

   const Parser = require('swagger-parser');
   Parser.validate('openapi.yaml').then(resolved => {
     console.log(JSON.stringify(resolved, null, 2));
   });
   

3. Open the spec in Swagger UI:
   • Start a simple HTTP server in the restored folder, e.g. npx serve ..
   • Navigate to http://localhost:5000/openapi.yaml.
   • Open the browser console to look for 404s or CORS errors.
   • Use the “Show resolved spec” toggle in the UI to compare the internal JSON with the output from swagger-cli validate.
4. Open the spec in Swagger Editor:
   • Drag the root openapi.yaml into the Editor.
   • Enable the “Show raw JSON” panel to see the Editor’s internal representation.
   • Check the console for warnings about missing refs.
5. Cross‑check:
   • If the Editor shows operations that Swagger UI does not, look for 404s in the UI console.
   • If Swagger UI shows an error but the Editor does not, the Editor’s relaxed resolver may be hiding a problem – validate again with swagger-cli.

Handling refs that move outside the restored folder

• Update the relative paths in openapi.yaml to point to the correct location, or
• Use the --cwd flag with swagger-cli to set the base directory, or
• Serve the external files from the same HTTP server and adjust the refs to use relative URLs.

There is no built‑in feature in either tool to automatically redirect external refs; you must adjust the file structure or provide the external files in the same HTTP context.

Uncertainty & follow‑up

Both tools rely on the same swagger-parser library, but different embedded versions can change resolution behaviour. If you notice inconsistent results, check the parser version in each tool’s package.json or run npm ls swagger-parser in the tool’s install folder.

One detail that would change the recommendation is whether any $ref points to a file outside the restored directory. If that is the case, the above workflow still applies, but you’ll need to either include those external files in the same HTTP server or adjust the paths to use absolute URLs that are reachable from the client.

Ask

Does any $ref in your restored backup point to a file outside the restored folder?