fix(swagger): avoid route collision, respect global Swagger flag, normalize app root

Address review feedback:
- Gate the APPLICATION_ROOT-aware Swagger/OpenAPI registration on
  FAB_API_SWAGGER_UI so the global Swagger disable still takes precedence.
- Suppress FAB's default OpenAPI/Swagger views (FAB_ADD_OPENAPI_VIEWS) when
  the prefix-aware variant is active, so the two don't register duplicate URL
  rules for /api/<version>/_openapi and /swagger/<version>.
- Normalize APPLICATION_ROOT (treat '/' as empty, strip trailing slash) so the
  Swagger UI spec URL is not built as a protocol-relative '//api/...' URL.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

superset/config.py

@@ -393,6 +393,13 @@ LOGO_RIGHT_TEXT: Callable[[], str] | str = ""
 # ex: http://localhost:8080/swagger/v1
 FAB_API_SWAGGER_UI = True
 
+# 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
 # ----------------------------------------------------

superset/initialization/__init__.py

@@ -64,6 +64,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
@@ -463,6 +464,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
@@ -911,6 +921,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_url_map_converters(self) -> None:

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,
+)

superset/openapi/manager.py

@@ -0,0 +1,131 @@
+# 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 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:
+        app_root = normalize_app_root(current_app.config.get("APPLICATION_ROOT", "/"))
+        default_server = {"url": request.host_url.rstrip("/") + (app_root 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:
+        app_root = normalize_app_root(current_app.config.get("APPLICATION_ROOT"))
+        openapi_uri = (app_root + 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,
+        )

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.

tests/unit_tests/openapi/test_manager.py

@@ -0,0 +1,49 @@
+# 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 marshmallow import Schema
+
+from superset.openapi.manager import normalize_app_root, 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_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"