You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by ru...@apache.org on 2026/07/13 22:47:16 UTC
(superset) branch master updated: fix(swagger): support URL prefix via APPLICATION_ROOT in OpenAPI and Swagger UI (#40908)
This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new 3c648ca2645 fix(swagger): support URL prefix via APPLICATION_ROOT in OpenAPI and Swagger UI (#40908)
3c648ca2645 is described below
commit 3c648ca2645f35b02b7c96412930c94410d45fbf
Author: Evan Rusackas <ev...@preset.io>
AuthorDate: Mon Jul 13 15:47:09 2026 -0700
fix(swagger): support URL prefix via APPLICATION_ROOT in OpenAPI and Swagger UI (#40908)
Co-authored-by: Claude Code <no...@anthropic.com>
Co-authored-by: rsbhatti <ra...@gmail.com>
---
superset/config.py | 7 ++
superset/initialization/__init__.py | 21 +++++
superset/openapi/__init__.py | 20 +++++
superset/openapi/manager.py | 143 +++++++++++++++++++++++++++++++
tests/unit_tests/openapi/__init__.py | 16 ++++
tests/unit_tests/openapi/test_manager.py | 77 +++++++++++++++++
6 files changed, 284 insertions(+)
diff --git a/superset/config.py b/superset/config.py
index cf4a8707f1a..9b0e6e252c8 100644
--- a/superset/config.py
+++ b/superset/config.py
@@ -469,6 +469,13 @@ FAB_API_SWAGGER_UI = utils.cast_to_boolean(
os.environ.get("SUPERSET_ENABLE_SWAGGER_UI", False)
)
+# Enables an APPLICATION_ROOT-aware Swagger UI and OpenAPI spec, for Superset
+# deployments served behind a URL prefix (reverse proxy). When True, the spec
+# is exposed at ``/api/<version>/_openapi`` and the Swagger UI resolves it
+# through APPLICATION_ROOT. Defaults to False (standard FAB Swagger UI).
+# ex: http://localhost:8080/<prefix>/swagger/v1
+FAB_API_SWAGGER_UI_SUPERSET_APP_ROOT = False
+
# ----------------------------------------------------
# AUTHENTICATION CONFIG
# ----------------------------------------------------
diff --git a/superset/initialization/__init__.py b/superset/initialization/__init__.py
index 336f666b9e2..c70f4844233 100644
--- a/superset/initialization/__init__.py
+++ b/superset/initialization/__init__.py
@@ -66,6 +66,7 @@ from superset.extensions import (
talisman,
)
from superset.extensions.context import extension_context
+from superset.openapi import SupersetOpenApi, SupersetSwaggerView
from superset.security import SupersetSecurityManager
from superset.semantic_layers.labels import database_connections_menu_label
from superset.sql.parse import SQLGLOT_DIALECTS
@@ -474,6 +475,15 @@ class SupersetAppInitializer: # pylint: disable=too-many-public-methods
appbuilder.add_view_no_menu(RedirectView)
appbuilder.add_view_no_menu(RoleRestAPI)
appbuilder.add_view_no_menu(UserInfoView)
+ # Only register the APPLICATION_ROOT-aware Swagger UI / OpenAPI spec when
+ # Swagger is enabled globally (``FAB_API_SWAGGER_UI``). This preserves the
+ # global disable contract so operators who turn Swagger off don't get the
+ # API documentation re-exposed by the prefix-aware variant.
+ if self.config.get("FAB_API_SWAGGER_UI") and self.config.get(
+ "FAB_API_SWAGGER_UI_SUPERSET_APP_ROOT", False
+ ):
+ appbuilder.add_api(SupersetOpenApi)
+ appbuilder.add_view_no_menu(SupersetSwaggerView)
#
# Add links
@@ -1206,6 +1216,17 @@ class SupersetAppInitializer: # pylint: disable=too-many-public-methods
appbuilder.indexview = SupersetIndexView
appbuilder.security_manager_class = custom_sm
+
+ # The APPLICATION_ROOT-aware Swagger UI and OpenAPI spec replace FAB's
+ # default views at the same routes (``/api/<version>/_openapi`` and
+ # ``/swagger/<version>``). Suppress FAB's default registration so the two
+ # implementations don't create duplicate URL rules for the same path,
+ # which would otherwise leave FAB's (non-prefix-aware) handler in charge.
+ if self.config.get("FAB_API_SWAGGER_UI") and self.config.get(
+ "FAB_API_SWAGGER_UI_SUPERSET_APP_ROOT", False
+ ):
+ self.superset_app.config["FAB_ADD_OPENAPI_VIEWS"] = False
+
appbuilder.init_app(self.superset_app, db.session)
def configure_subjects(self) -> None:
diff --git a/superset/openapi/__init__.py b/superset/openapi/__init__.py
new file mode 100644
index 00000000000..5108157ef39
--- /dev/null
+++ b/superset/openapi/__init__.py
@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from superset.openapi.manager import ( # noqa: F401
+ SupersetOpenApi,
+ SupersetSwaggerView,
+)
diff --git a/superset/openapi/manager.py b/superset/openapi/manager.py
new file mode 100644
index 00000000000..a905eae6278
--- /dev/null
+++ b/superset/openapi/manager.py
@@ -0,0 +1,143 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""APPLICATION_ROOT-aware OpenAPI spec and Swagger UI.
+
+Serves the OpenAPI spec and Swagger UI in a way that works when Superset is
+deployed behind a URL prefix (reverse proxy) via ``APPLICATION_ROOT``. Enabled
+by the ``FAB_API_SWAGGER_UI_SUPERSET_APP_ROOT`` config flag.
+"""
+
+from typing import Any
+
+from apispec import APISpec
+from apispec.ext.marshmallow import MarshmallowPlugin
+from apispec.ext.marshmallow.common import resolve_schema_cls
+from flask import current_app, request
+from flask_appbuilder.api import BaseApi, expose, protect, safe
+from flask_appbuilder.baseviews import BaseView
+from flask_appbuilder.security.decorators import has_access
+
+from superset.superset_typing import FlaskResponse
+
+
+def normalize_app_root(app_root: str | None) -> str:
+ """Normalize ``APPLICATION_ROOT`` into a prefix safe for URL concatenation.
+
+ Flask defaults ``APPLICATION_ROOT`` to ``"/"``. Concatenating that (or any
+ value with a trailing slash) directly with a leading-slash path produces an
+ invalid protocol-relative URL such as ``//api/v1/_openapi``. Treat ``"/"`` as
+ an empty prefix and strip any trailing slash so the result is either empty or
+ a clean ``/prefix``.
+ """
+ if not app_root:
+ return ""
+ return app_root.rstrip("/")
+
+
+def resolve_url_prefix() -> str:
+ """Resolve the URL prefix used to build OpenAPI/Swagger links.
+
+ Prefer the request's script root so reverse-proxy prefixes exposed via
+ ``X-Forwarded-Prefix`` / ``SCRIPT_NAME`` keep working (this is what FAB's
+ stock Swagger view does), and fall back to a normalized ``APPLICATION_ROOT``
+ when no script root is present.
+ """
+ return request.script_root or normalize_app_root(
+ current_app.config.get("APPLICATION_ROOT")
+ )
+
+
+def resolver(schema: Any) -> str:
+ schema_cls = resolve_schema_cls(schema)
+ name = schema_cls.__name__
+ if name == "MetaSchema" and hasattr(schema_cls, "Meta"):
+ return f"{schema_cls.Meta.parent_schema_name}.{schema_cls.Meta.model.__name__}"
+ if name.endswith("Schema"):
+ return name[:-6] or name
+ return name
+
+
+class SupersetOpenApi(BaseApi):
+ route_base = "/api"
+ allow_browser_login = True
+
+ @expose("/<version>/_openapi")
+ @protect()
+ @safe
+ def get(self, version: str) -> FlaskResponse:
+ """Render the OpenAPI spec for every view that belongs to a version.
+ ---
+ get:
+ description: >-
+ Get the OpenAPI spec for a specific API version
+ parameters:
+ - in: path
+ schema:
+ type: string
+ name: version
+ responses:
+ 200:
+ description: The OpenAPI spec
+ content:
+ application/json:
+ schema:
+ type: object
+ 404:
+ $ref: '#/components/responses/404'
+ 500:
+ $ref: '#/components/responses/500'
+ """
+ version_found = False
+ api_spec = self._create_api_spec(version)
+ for base_api in current_app.appbuilder.baseviews:
+ if isinstance(base_api, BaseApi) and base_api.version == version:
+ base_api.add_api_spec(api_spec)
+ version_found = True
+ if version_found:
+ return self.response(200, **api_spec.to_dict())
+ return self.response_404()
+
+ @staticmethod
+ def _create_api_spec(version: str) -> APISpec:
+ prefix = resolve_url_prefix()
+ default_server = {"url": request.host_url.rstrip("/") + (prefix or "/")}
+ servers = current_app.config.get("FAB_OPENAPI_SERVERS", [default_server])
+ return APISpec(
+ title=current_app.appbuilder.app_name,
+ version=version,
+ openapi_version="3.0.2",
+ info={"description": current_app.appbuilder.app_name},
+ plugins=[MarshmallowPlugin(schema_name_resolver=resolver)],
+ servers=servers,
+ )
+
+
+class SupersetSwaggerView(BaseView):
+ route_base = "/swagger"
+ default_view = "show"
+ openapi_uri = "/api/{}/_openapi"
+
+ @expose("/<version>")
+ @has_access
+ def show(self, version: str) -> FlaskResponse:
+ openapi_uri = (resolve_url_prefix() + self.openapi_uri).format(version)
+ return self.render_template(
+ current_app.config.get(
+ "FAB_API_SWAGGER_TEMPLATE", "appbuilder/swagger/swagger.html"
+ ),
+ openapi_uri=openapi_uri,
+ )
diff --git a/tests/unit_tests/openapi/__init__.py b/tests/unit_tests/openapi/__init__.py
new file mode 100644
index 00000000000..13a83393a91
--- /dev/null
+++ b/tests/unit_tests/openapi/__init__.py
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
diff --git a/tests/unit_tests/openapi/test_manager.py b/tests/unit_tests/openapi/test_manager.py
new file mode 100644
index 00000000000..ba4c2cd3497
--- /dev/null
+++ b/tests/unit_tests/openapi/test_manager.py
@@ -0,0 +1,77 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+import pytest
+from flask import Flask
+from marshmallow import Schema
+
+from superset.openapi.manager import (
+ normalize_app_root,
+ resolve_url_prefix,
+ resolver,
+)
+
+
+@pytest.mark.parametrize(
+ "app_root,expected",
+ [
+ ("/", ""),
+ ("", ""),
+ (None, ""),
+ ("/prefix", "/prefix"),
+ ("/prefix/", "/prefix"),
+ ("/nested/prefix/", "/nested/prefix"),
+ ],
+)
+def test_normalize_app_root(app_root: str | None, expected: str) -> None:
+ assert normalize_app_root(app_root) == expected
+
+
+def test_resolve_url_prefix_prefers_script_root() -> None:
+ # A reverse-proxy prefix (X-Forwarded-Prefix / SCRIPT_NAME) must win over
+ # APPLICATION_ROOT so FAB's script_root behavior isn't dropped.
+ app = Flask(__name__)
+ app.config["APPLICATION_ROOT"] = "/config-root"
+ with app.test_request_context(environ_overrides={"SCRIPT_NAME": "/proxy-root"}):
+ assert resolve_url_prefix() == "/proxy-root"
+
+
+def test_resolve_url_prefix_falls_back_to_app_root() -> None:
+ app = Flask(__name__)
+ app.config["APPLICATION_ROOT"] = "/config-root"
+ with app.test_request_context():
+ assert resolve_url_prefix() == "/config-root"
+
+
+def test_resolve_url_prefix_empty_when_neither_set() -> None:
+ app = Flask(__name__)
+ app.config["APPLICATION_ROOT"] = "/"
+ with app.test_request_context():
+ assert resolve_url_prefix() == ""
+
+
+def test_resolver_strips_schema_suffix() -> None:
+ class FooSchema(Schema):
+ pass
+
+ assert resolver(FooSchema) == "Foo"
+
+
+def test_resolver_keeps_name_without_schema_suffix() -> None:
+ class Bar(Schema):
+ pass
+
+ assert resolver(Bar) == "Bar"