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"