feat: 新增@extend_schema装饰器声明接口以支持自动接入蓝鲸API网关

Author: Xinkai Yi

bk-plugin-framework/bk_plugin_framework/serializers.py

@@ -3,7 +3,7 @@
 
 
 def enveloper(serializer_class, many: bool = False):
-    """统一响应包装器（参考您的模式）"""
+    """统一响应包装器"""
     component_name = "Enveloped{}{}".format(
         serializer_class.__name__.replace("Serializer", ""),
         "List" if many else "",

bk-plugin-framework/bk_plugin_framework/services/bpf_service/api/callback.py

@@ -15,24 +15,36 @@
 
 from apigw_manager.apigw.decorators import apigw_require
 from bk_plugin_framework.runtime.callback.api import callback, parse_callback_token
+from bk_plugin_framework.serializers import enveloper
 from blueapps.account.decorators import login_exempt
 from django.utils.decorators import method_decorator
-from drf_yasg.utils import swagger_auto_schema
+from drf_spectacular.utils import extend_schema
+from rest_framework import serializers
 from rest_framework.decorators import action
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
 logger = logging.getLogger("bk_plugin")
 
 
+class PluginCallbackParamsSerializer(serializers.Serializer):
+    token = serializers.CharField(help_text="插件回调token", required=True)
+
+
+class PluginCallbackResponseSerializer(serializers.Serializer):
+    result = serializers.BooleanField(help_text="回调结果，True表示成功，False表示失败")
+    message = serializers.CharField(help_text="回调结果信息", required=False)
+
+
 @method_decorator(login_exempt, name="dispatch")
 @method_decorator(apigw_require, name="dispatch")
 class PluginCallback(APIView):
     authentication_classes = []  # csrf exempt
 
-    @swagger_auto_schema(
-        method="POST",
-        operation_summary="plugin callback",
+    @extend_schema(
+        summary="插件回调",
+        request=PluginCallbackParamsSerializer,
+        responses={200: enveloper(PluginCallbackResponseSerializer)},
     )
     @action(methods=["POST"], detail=True)
     def post(self, request, token):

bk-plugin-framework/bk_plugin_framework/services/bpf_service/api/invoke.py

@@ -14,6 +14,7 @@
 from apigw_manager.apigw.decorators import apigw_require
 from bk_plugin_framework.hub import VersionHub
 from bk_plugin_framework.runtime.executor import BKPluginExecutor
+from bk_plugin_framework.serializers import enveloper
 from bk_plugin_framework.services.bpf_service.api.permissions import (
     ScopeAllowPermission,
 )
@@ -22,7 +23,7 @@
 )
 from blueapps.account.decorators import login_exempt
 from django.utils.decorators import method_decorator
-from drf_yasg.utils import swagger_auto_schema
+from drf_spectacular.utils import extend_schema
 from rest_framework import serializers, status
 from rest_framework.decorators import action
 from rest_framework.exceptions import ValidationError
@@ -55,11 +56,10 @@ class Invoke(APIView):
     authentication_classes = []  # csrf exempt
     permission_classes = [ScopeAllowPermission]
 
-    @swagger_auto_schema(
-        method="POST",
-        operation_summary="Invoke specific version plugin",
-        request_body=InvokeParamsSerializer,
-        responses={200: InvokeResponseSerializer},
+    @extend_schema(
+        summary="插件调用",
+        request=InvokeParamsSerializer,
+        responses={200: enveloper(InvokeResponseSerializer)},
     )
     @action(methods=["POST"], detail=True)
     def post(self, request, version):

bk-plugin-framework/bk_plugin_framework/services/bpf_service/api/plugin_api_dispatch.py

@@ -15,6 +15,7 @@
 from urllib.parse import urlsplit
 
 from apigw_manager.apigw.decorators import apigw_require
+from bk_plugin_framework.serializers import enveloper
 from bk_plugin_framework.services.bpf_service.api.permissions import (
     ScopeAllowPermission,
 )
@@ -25,7 +26,7 @@
 from django.test import RequestFactory
 from django.urls import Resolver404, resolve
 from django.utils.decorators import method_decorator
-from drf_yasg.utils import swagger_auto_schema
+from drf_spectacular.utils import extend_schema
 from rest_framework import serializers, status
 from rest_framework.decorators import action
 from rest_framework.exceptions import ValidationError
@@ -76,11 +77,10 @@ class PluginAPIDispatch(APIView):
     authentication_classes = []  # csrf exempt
     permission_classes = [ScopeAllowPermission]
 
-    @swagger_auto_schema(
-        method="POST",
-        operation_summary="Plugin API dispatch",
-        request_body=PluginAPIDispatchParamsSerializer,
-        responses={200: PluginAPIDispatchResponseSerializer},
+    @extend_schema(
+        summary="插件API分发",
+        request=PluginAPIDispatchParamsSerializer,
+        responses={200: enveloper(PluginAPIDispatchResponseSerializer)},
     )
     @action(methods=["POST"], detail=True)
     def post(self, request):

bk-plugin-framework/bk_plugin_framework/services/bpf_service/api/schedule.py

@@ -13,12 +13,13 @@
 import logging
 
 from bk_plugin_framework.runtime.schedule.models import Schedule as ScheduleModel
+from bk_plugin_framework.serializers import enveloper
 from bk_plugin_framework.services.bpf_service.api.serializers import (
     StandardResponseSerializer,
 )
 from blueapps.account.decorators import login_exempt
 from django.utils.decorators import method_decorator
-from drf_yasg.utils import swagger_auto_schema
+from drf_spectacular.utils import extend_schema
 from rest_framework import permissions, serializers
 from rest_framework.decorators import action
 from rest_framework.response import Response
@@ -27,6 +28,10 @@
 logger = logging.getLogger("root")
 
 
+class ScheduleParamsSerializer(serializers.Serializer):
+    trace_id = serializers.CharField(help_text="插件调用 trace id")
+
+
 class ScheduleResponseSerializer(StandardResponseSerializer):
     class ScheduleDataSerializer(serializers.Serializer):
         class Meta:
@@ -48,10 +53,10 @@ class Schedule(APIView):
 
     permission_classes = [permissions.AllowAny]
 
-    @swagger_auto_schema(
-        method="GET",
-        operation_summary="Get plugin schedule detail with trace_id",
-        responses={200: ScheduleResponseSerializer},
+    @extend_schema(
+        summary="获取插件调度详情",
+        request=ScheduleParamsSerializer,
+        responses={200: enveloper(ScheduleResponseSerializer)},
     )
     @action(methods=["GET"], detail=True)
     def get(self, request, trace_id):