From 36f525eb342aa4f0304fd31c76922f32b6225654 Mon Sep 17 00:00:00 2001
From: chbndrhnns <chbndrhnns@users.noreply.github.com>
Date: Mon, 22 Jun 2026 15:04:55 +0200
Subject: [PATCH] Add option to preserve refs in served spec

---
 connexion/middleware/swagger_ui.py |  5 ++++-
 connexion/options.py               |  8 ++++++++
 tests/api/test_bootstrap.py        | 13 +++++++++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/connexion/middleware/swagger_ui.py b/connexion/middleware/swagger_ui.py
index e4a91c0fe..c9cd61518 100644
--- a/connexion/middleware/swagger_ui.py
+++ b/connexion/middleware/swagger_ui.py
@@ -70,7 +70,10 @@ def _spec_for_prefix(self, request) -> dict:
         This is needed when behind a path-altering reverse proxy.
         """
         base_path = self._base_path_for_prefix(request)
-        return self.specification.with_base_path(base_path).spec
+        specification = self.specification.with_base_path(base_path)
+        if self.options.resolve_spec_refs:
+            return specification.spec
+        return specification.raw
 
     def add_openapi_json(self):
         """
diff --git a/connexion/options.py b/connexion/options.py
index 14b1b5bca..c4e461dbd 100644
--- a/connexion/options.py
+++ b/connexion/options.py
@@ -24,6 +24,8 @@ class SwaggerUIOptions:
 
     :param serve_spec: Whether to serve the Swagger / OpenAPI Specification
     :param spec_path: Where to serve the Swagger / OpenAPI Specification
+    :param resolve_spec_refs: Whether to resolve references in the served Swagger / OpenAPI
+        Specification.
 
     :param swagger_ui: Whether to serve the Swagger UI
     :param swagger_ui_path: Where to serve the Swagger UI
@@ -37,6 +39,7 @@ class SwaggerUIOptions:
 
     serve_spec: bool = True
     spec_path: t.Optional[str] = None
+    resolve_spec_refs: bool = True
 
     swagger_ui: bool = True
     swagger_ui_config: dict = dataclasses.field(default_factory=dict)
@@ -76,6 +79,11 @@ def openapi_spec_path(self) -> str:
         """Path to host the Swagger UI."""
         return self._options.spec_path or self.spec_path
 
+    @property
+    def resolve_spec_refs(self) -> bool:
+        """Whether to resolve references in the served Swagger / OpenAPI Specification."""
+        return self._options.resolve_spec_refs
+
     @property
     def swagger_ui_available(self) -> bool:
         """Whether to make the Swagger UI available."""
diff --git a/tests/api/test_bootstrap.py b/tests/api/test_bootstrap.py
index 266ac36c4..b61643666 100644
--- a/tests/api/test_bootstrap.py
+++ b/tests/api/test_bootstrap.py
@@ -130,6 +130,19 @@ def test_swagger_json_app(simple_api_spec_dir, spec):
     url = url.format(spec=spec.replace("yaml", "json"))
     spec_json = app_client.get(url)
     assert spec_json.status_code == 200
+    assert '"$ref"' not in spec_json.text
+
+
+def test_swagger_json_can_preserve_refs(simple_api_spec_dir, spec):
+    """Verify the spec json file can preserve the authored references."""
+    app = App(__name__, specification_dir=simple_api_spec_dir)
+    app.add_api(spec, swagger_ui_options=SwaggerUIOptions(resolve_spec_refs=False))
+    app_client = app.test_client()
+    url = "/v1.0/{spec}"
+    url = url.format(spec=spec.replace("yaml", "json"))
+    spec_json = app_client.get(url)
+    assert spec_json.status_code == 200
+    assert '"$ref"' in spec_json.text
 
 
 def test_swagger_yaml_app(simple_api_spec_dir, spec):