feat: 从 drf_yasg 迁移到 drf_spectacular，修复子路径部署问题

- urls.py: 将 drf_yasg 替换为 drf_spectacular 的 SpectacularAPIView/SwaggerView/RedocView
- default.py: 添加子路径支持（FORCE_SCRIPT_NAME/STATIC_URL），添加 SPECTACULAR_SETTINGS 配置
- schema.py: 新增 IgnoreExcludeAutoSchema 和 extend_schema patch，使 exclude=True 不生效
- pyproject.toml: 移除 drf-yasg 依赖

Author: dengyh

runtime/bk-plugin-runtime/bk_plugin_runtime/config/default.py

@@ -239,7 +239,16 @@ def logging_addition_settings(logging_dict):
     "DEFAULT_PERMISSION_CLASSES": [
         "apigw_manager.drf.permission.ApiGatewayPermission",
     ],
-    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+    "DEFAULT_SCHEMA_CLASS": "bk_plugin_runtime.schema.IgnoreExcludeAutoSchema",
+}
+
+# drf-spectacular 配置
+import bk_plugin_runtime.schema  # noqa: 应用 monkey-patch，使 @extend_schema(exclude=True) 不生效
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "PluginService API",
+    "VERSION": "v1",
+    "SERVE_INCLUDE_SCHEMA": False,
 }
 
 
@@ -266,6 +275,15 @@ def logging_addition_settings(logging_dict):
 BK_APIGW_STAGE_BACKEND_HOST = f"{app_scheme}://{app_domain}"
 BK_APIGW_STAGE_BACKEND_SUBPATH = app_subpath
 
+# 子路径配置：当应用部署在子路径下时（如 /bk-plugin-demo-g/），
+# 需要设置 FORCE_SCRIPT_NAME 和 STATIC_URL 以确保 admin 样式和静态资源正常加载
+if app_subpath:
+    FORCE_SCRIPT_NAME = f"/{app_subpath}"
+    STATIC_URL = f"/{app_subpath}/static/"
+else:
+    FORCE_SCRIPT_NAME = ""
+    STATIC_URL = "/static/"
+
 # 网关同步 API 文档语言, zh/en, 如果配置了BK_APIGW_RESOURCE_DOCS_BASE_DIR（使用自定义文档）, 那么必须将这个变量置空
 BK_APIGW_RELEASE_DOC_LANGUAGE = os.getenv("BK_APIGW_RELEASE_DOC_LANGUAGE", "")
 # 在项目 docs目录下，通过 markdown文档自动化导入中英文文档; 注意markdown文件名必须等于接口的 operation_id; 见 demo 示例
@@ -302,7 +320,8 @@ def logging_addition_settings(logging_dict):
 # APIGW MANAGER
 BK_APP_CODE = os.getenv("BKPAAS_APP_ID")
 BK_APP_SECRET = os.getenv("BKPAAS_APP_SECRET")
-BK_APIGW_NAME = os.getenv("BKPAAS_BK_PLUGIN_APIGW_NAME")
+# 兼容不同部署环境的变量名
+BK_APIGW_NAME = os.getenv("BKPAAS_BK_PLUGIN_APIGW_NAME") or os.getenv("BK_PLUGIN_APIGW_NAME")
 # 兼容旧版环境变量 & PaaS V3 默认注入变量
 BK_API_URL_TMPL = (
     os.getenv("BK_APIGW_MANAGER_URL_TMPL") or os.getenv("BK_APIGW_MANAGER_URL_TEMPL") or os.getenv("BK_API_URL_TMPL")

runtime/bk-plugin-runtime/bk_plugin_runtime/schema.py

@@ -0,0 +1,21 @@
+import drf_spectacular.openapi
+import drf_spectacular.utils
+
+
+class IgnoreExcludeAutoSchema(drf_spectacular.openapi.AutoSchema):
+    """忽略 @extend_schema(exclude=True)，将所有 API 暴露到 Swagger 文档中"""
+
+    def is_excluded(self) -> bool:
+        return False
+
+
+# Patch extend_schema 装饰器，使 exclude 参数无效
+_original_extend_schema = drf_spectacular.utils.extend_schema
+
+
+def _patched_extend_schema(*args, exclude=None, **kwargs):
+    """将 exclude 强制设为 None，使 @extend_schema(exclude=True) 不生效"""
+    return _original_extend_schema(*args, exclude=None, **kwargs)
+
+
+drf_spectacular.utils.extend_schema = _patched_extend_schema

runtime/bk-plugin-runtime/bk_plugin_runtime/urls.py

@@ -12,26 +12,14 @@
 from django.conf import settings
 from django.contrib import admin
 from django.urls import include, re_path
-from drf_yasg import openapi
-from drf_yasg.views import get_schema_view
-from rest_framework import permissions
-
-schema_view = get_schema_view(
-    openapi.Info(
-        title="PluginService API",
-        default_version="v1",
-    ),
-    public=True,
-    permission_classes=(permissions.AllowAny,),
-)
-
+from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
 
 urlpatterns = [
     re_path(r"^admin/", admin.site.urls),
     re_path(r"^account/", include("blueapps.account.urls")),
     re_path(r"^i18n/", include("django.conf.urls.i18n")),
-    re_path(r"^swagger(?P<format>\.json|\.yaml)$", schema_view.without_ui(cache_timeout=0), name="schema-json"),
-    re_path(r"^redoc/$", schema_view.with_ui("redoc", cache_timeout=0), name="schema-redoc"),
+    re_path(r"^schema/$", SpectacularAPIView.as_view(), name="schema"),
+    re_path(r"^redoc/$", SpectacularRedocView.as_view(url_name="schema"), name="redoc"),
     re_path(r"^bk_plugin/", include("bk_plugin_framework.services.bpf_service.urls")),
 ]
 
@@ -41,11 +29,11 @@
 
     urlpatterns.extend(
         [
-            re_path(r"^swagger/$", schema_view.with_ui("swagger", cache_timeout=0), name="schema-swagger-ui"),
+            re_path(r"^swagger/$", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
             re_path(r"^$", debug_panel, name="debug-panel"),
         ]
     )
 else:
     urlpatterns.append(
-        re_path(r"^$", schema_view.with_ui("swagger", cache_timeout=0), name="schema-swagger-ui"),
+        re_path(r"^$", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
     )

runtime/bk-plugin-runtime/pyproject.toml

@@ -12,7 +12,6 @@ Django = ">=2.2.6,<5"
 pymysql = ">=1,<2"
 gunicorn = ">=19.6.0"
 djangorestframework = "^3.15"
-drf-yasg = "^1.21.5"
 raven = "^6.5.0"
 ddtrace = "^0.14.1"
 django-cors-headers = "^4.0.0"