External $ref base URL configuration for OpenAPI 3.1 in Swagger UI and Springdoc

In OpenAPI 3.1, the authoritative base URL for relative $ref values is not strictly defined by the specification. This creates a divergence: client-side tools like Swagger UI typically resolve references against the URL of the specification document, while server-side frameworks like Springdoc often resolve them against the application's context path or file system.

Resolution Logic Overview

• Swagger UI / ReDoc: These tools operate in the browser. They resolve relative paths relative to the fetch URL. If your spec is at /api/v1/docs.json, a reference to ./schemas/user.json will be fetched from /api/v1/schemas/user.json.
• Springdoc (Spring): This library resolves references on the server. It looks for files on the classpath or within the application context. If the app is behind a proxy, the generated paths in the JSON may not match the browser-accessible paths unless the context path is explicitly configured.
• OpenAPI Generator: This tool resolves references during build time. It resolves them relative to the file system path where the specification resides, regardless of the eventual deployment URL.

How to Override Base URL Behavior

Since there is no standard "base URL" property in the OpenAPI spec, you must use tool-specific configurations to ensure consistency:

1. Springdoc Configuration

If your API is behind a reverse proxy or has a custom context path, use the server-base-path property to ensure Springdoc generates the correct relative paths for $ref resolution:

# application.properties
springdoc.swagger-ui.base-path=/my-custom-proxy

2. Swagger UI Customization

If Swagger UI is failing to resolve references because of a path structure mismatch, you can use the url property in the initialization configuration to point to an absolute location, or use the request-inter plugin to intercept and rewrite requests:

// Swagger UI initialization
const ui = SwaggerUI({
  url: "https://cdn.example.com/v3/api-docs",
  domId: "swagger-ui",
});

Verification Strategy

To verify your strategy remains consistent across rendering and generation without duplication, follow these steps:

1. Network Inspection: Open the browser's Network tab while loading Swagger UI. Filter for the file name mentioned in your $ref. Ensure the requested URL matches your expected directory structure.
2. Schema Validation: Use a tool like spectral to validate the generated JSON. This ensures that the $ref paths are logically valid relative to the document's root.
3. Generator Audit: Check the output code from OpenAPI Generator. If the schemas are duplicated, it indicates the generator performed "inline" resolution because it couldn't resolve the external file correctly.

Note: If you are using a CDN, ensure the Content-Type is set to application/json and Access-Control-Allow-Origin headers are present, or the browser will block the resolution of external/relative references.