From ab28503d53206215ecd7746c58b4ab78a15347b7 Mon Sep 17 00:00:00 2001 From: dengyh Date: Fri, 10 Apr 2026 14:22:12 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BB=8E=20drf=5Fyasg=20=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E5=88=B0=20drf=5Fspectacular=EF=BC=8C=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=E5=AD=90=E8=B7=AF=E5=BE=84=E9=83=A8=E7=BD=B2=E9=97=AE?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 依赖 --- .../bk_plugin_runtime/config/default.py | 20 ++++++++++++++++- .../bk_plugin_runtime/schema.py | 21 ++++++++++++++++++ .../bk_plugin_runtime/urls.py | 22 +++++-------------- runtime/bk-plugin-runtime/pyproject.toml | 1 - 4 files changed, 45 insertions(+), 19 deletions(-) create mode 100644 runtime/bk-plugin-runtime/bk_plugin_runtime/schema.py diff --git a/runtime/bk-plugin-runtime/bk_plugin_runtime/config/default.py b/runtime/bk-plugin-runtime/bk_plugin_runtime/config/default.py index fe59bba..a8b1035 100644 --- a/runtime/bk-plugin-runtime/bk_plugin_runtime/config/default.py +++ b/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 示例 diff --git a/runtime/bk-plugin-runtime/bk_plugin_runtime/schema.py b/runtime/bk-plugin-runtime/bk_plugin_runtime/schema.py new file mode 100644 index 0000000..b0e9f48 --- /dev/null +++ b/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 diff --git a/runtime/bk-plugin-runtime/bk_plugin_runtime/urls.py b/runtime/bk-plugin-runtime/bk_plugin_runtime/urls.py index 032a00b..8077c5b 100644 --- a/runtime/bk-plugin-runtime/bk_plugin_runtime/urls.py +++ b/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\.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"), ) diff --git a/runtime/bk-plugin-runtime/pyproject.toml b/runtime/bk-plugin-runtime/pyproject.toml index 1f6fe67..5b430c6 100644 --- a/runtime/bk-plugin-runtime/pyproject.toml +++ b/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"