docs(apis/web): serializers docs (#291)

* docs(apis/web): serializers docs * fix(typo): help_text
TencentBlueKing · Oct 12, 2023 · f241790 · f241790
1 parent c7e6f76
commit f241790
Show file tree

Hide file tree

Showing 6 changed files with 134 additions and 120 deletions.
diff --git a/src/dashboard/apigateway/apigateway/apis/web/access_log/serializers.py b/src/dashboard/apigateway/apigateway/apis/web/access_log/serializers.py
@@ -21,13 +21,13 @@
 
 
 class RequestLogQueryInputSLZ(serializers.Serializer):
-    stage_id = serializers.IntegerField(required=True)
-    query = serializers.CharField(label="查询条件", required=False, allow_blank=True)
-    time_range = serializers.IntegerField(label="时间范围", required=False, min_value=0)
-    time_start = serializers.IntegerField(label="起始时间", required=False, min_value=0)
-    time_end = serializers.IntegerField(label="结束时间", required=False, min_value=0)
-    offset = serializers.IntegerField(label="偏移量", required=False, min_value=0, default=0)
-    limit = serializers.IntegerField(label="限制条数", required=False, min_value=1, default=10)
+    stage_id = serializers.IntegerField(required=True, help_text="环境 ID")
+    query = serializers.CharField(label="查询条件", required=False, allow_blank=True, help_text="查询条件")
+    time_range = serializers.IntegerField(label="时间范围", required=False, min_value=0, help_text="时间范围")
+    time_start = serializers.IntegerField(label="起始时间", required=False, min_value=0, help_text="起始时间")
+    time_end = serializers.IntegerField(label="结束时间", required=False, min_value=0, help_text="结束时间")
+    offset = serializers.IntegerField(label="偏移量", required=False, min_value=0, default=0, help_text="偏移量")
+    limit = serializers.IntegerField(label="限制条数", required=False, min_value=1, default=10, help_text="限制条数")
 
     def validate(self, data):
         if not (data.get("time_start") and data.get("time_end") or data.get("time_range")):
@@ -36,43 +36,43 @@ def validate(self, data):
 
 
 class TimeChartOutputSLZ(serializers.Serializer):
-    series = serializers.ListField(child=serializers.IntegerField())
-    timeline = serializers.ListField(child=serializers.IntegerField())
+    series = serializers.ListField(child=serializers.IntegerField(), help_text="时间序列")
+    timeline = serializers.ListField(child=serializers.IntegerField(), help_text="时间轴")
 
 
 class RequestLogOutputSLZ(serializers.Serializer):
-    request_id = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    timestamp = serializers.IntegerField(required=False, allow_null=True)
-    stage = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    resource_id = serializers.IntegerField(required=False, allow_null=True)
-    resource_name = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    app_code = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    client_ip = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    method = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    http_host = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    http_path = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    backend_method = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    backend_scheme = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    backend_host = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    backend_path = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    params = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    body = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    response_body = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    status = serializers.IntegerField(required=False, allow_null=True)
-    headers = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    request_duration = serializers.IntegerField(required=False, allow_null=True)
-    backend_duration = serializers.IntegerField(required=False, allow_null=True)
-    code_name = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    error = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    response_desc = serializers.CharField(required=False, allow_null=True, allow_blank=True)
+    request_id = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求 ID")
+    timestamp = serializers.IntegerField(required=False, allow_null=True, help_text="请求时间戳")
+    stage = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="环境")
+    resource_id = serializers.IntegerField(required=False, allow_null=True, help_text="资源 ID")
+    resource_name = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="资源名称")
+    app_code = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="应用编码")
+    client_ip = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="客户端 IP")
+    method = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求方法")
+    http_host = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求域名")
+    http_path = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求路径")
+    backend_method = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="后端请求方法")
+    backend_scheme = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="后端请求协议")
+    backend_host = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="后端请求域名")
+    backend_path = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="后端请求路径")
+    params = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求参数")
+    body = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="请求体")
+    response_body = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="响应体")
+    status = serializers.IntegerField(required=False, allow_null=True, help_text="响应状态码")
+    headers = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="响应头")
+    request_duration = serializers.IntegerField(required=False, allow_null=True, help_text="请求耗时")
+    backend_duration = serializers.IntegerField(required=False, allow_null=True, help_text="后端请求耗时")
+    code_name = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="状态码名称")
+    error = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="错误")
+    response_desc = serializers.CharField(required=False, allow_null=True, allow_blank=True, help_text="响应描述")
 
 
 class LogLinkOutputSLZ(serializers.Serializer):
-    link = serializers.CharField(read_only=True)
+    link = serializers.CharField(read_only=True, help_text="链接地址")
 
 
 class LogDetailQueryInputSLZ(serializers.Serializer):
-    bk_nonce = serializers.IntegerField()
-    bk_timestamp = serializers.IntegerField()
-    bk_signature = serializers.CharField()
-    shared_by = serializers.CharField()
+    bk_nonce = serializers.IntegerField(help_text="随机数")
+    bk_timestamp = serializers.IntegerField(help_text="时间戳")
+    bk_signature = serializers.CharField(help_text="签名")
+    shared_by = serializers.CharField(help_text="分享人")
diff --git a/src/dashboard/apigateway/apigateway/apis/web/api_test/serializers.py b/src/dashboard/apigateway/apigateway/apis/web/api_test/serializers.py
@@ -25,12 +25,12 @@
 
 
 class AuthorizationSLZ(serializers.Serializer):
-    bk_app_code = serializers.CharField(allow_blank=True, required=False)
-    bk_app_secret = serializers.CharField(allow_blank=True, required=False)
-    bk_ticket = serializers.CharField(allow_blank=True, required=False)
-    bk_token = serializers.CharField(allow_blank=True, required=False)
-    uin = serializers.CharField(allow_blank=True, required=False)
-    skey = serializers.CharField(allow_blank=True, required=False)
+    bk_app_code = serializers.CharField(allow_blank=True, required=False, help_text="蓝鲸应用编码")
+    bk_app_secret = serializers.CharField(allow_blank=True, required=False, help_text="蓝鲸应用密钥")
+    bk_ticket = serializers.CharField(allow_blank=True, required=False, help_text="蓝鲸用户票据")
+    bk_token = serializers.CharField(allow_blank=True, required=False, help_text="蓝鲸用户票据")
+    uin = serializers.CharField(allow_blank=True, required=False, help_text="uin")
+    skey = serializers.CharField(allow_blank=True, required=False, help_text="skey")
 
     def validate_uin(self, value):
         try:
@@ -43,17 +43,17 @@ def validate(self, data: Dict[str, str]) -> Dict[str, str]:
 
 
 class APITestInputSLZ(serializers.Serializer):
-    stage_id = serializers.IntegerField()
-    resource_id = serializers.IntegerField()
-    method = serializers.ChoiceField(choices=HTTP_METHOD_CHOICES)
-    subpath = serializers.CharField(allow_blank=True, required=False)
-    headers = serializers.DictField(child=serializers.CharField(), allow_empty=True)
-    path_params = serializers.DictField(child=serializers.CharField(), allow_empty=True)
-    query_params = serializers.DictField(child=serializers.CharField(), allow_empty=True)
-    body = serializers.CharField(allow_blank=True, required=False)
-    use_test_app = serializers.BooleanField()
-    use_user_from_cookies = serializers.BooleanField(required=False, default=False)
-    authorization = AuthorizationSLZ(required=False, allow_null=True)
+    stage_id = serializers.IntegerField(help_text="环境 ID")
+    resource_id = serializers.IntegerField(help_text="资源 ID")
+    method = serializers.ChoiceField(choices=HTTP_METHOD_CHOICES, help_text="HTTP 方法")
+    subpath = serializers.CharField(allow_blank=True, required=False, help_text="子路径")
+    headers = serializers.DictField(child=serializers.CharField(), allow_empty=True, help_text="请求头")
+    path_params = serializers.DictField(child=serializers.CharField(), allow_empty=True, help_text="路径参数")
+    query_params = serializers.DictField(child=serializers.CharField(), allow_empty=True, help_text="查询参数")
+    body = serializers.CharField(allow_blank=True, required=False, help_text="请求体")
+    use_test_app = serializers.BooleanField(help_text="是否使用测试应用")
+    use_user_from_cookies = serializers.BooleanField(required=False, default=False, help_text="是否使用 cookies 中的用户信息")
+    authorization = AuthorizationSLZ(required=False, allow_null=True, help_text="认证信息")
 
     def validate(self, data: Dict[str, Any]) -> Dict[str, Any]:
         data.setdefault("authorization", {})
@@ -64,8 +64,8 @@ def validate(self, data: Dict[str, Any]) -> Dict[str, Any]:
 
 
 class APITestOutputSLZ(serializers.Serializer):
-    status_code = serializers.IntegerField()
-    proxy_time = serializers.IntegerField()
-    size = serializers.FloatField()
-    body = serializers.CharField()
-    headers = serializers.DictField()
+    status_code = serializers.IntegerField(help_text="HTTP 状态码")
+    proxy_time = serializers.IntegerField(help_text="网关代理耗时")
+    size = serializers.FloatField(help_text="响应体大小")
+    body = serializers.CharField(help_text="响应体内容")
+    headers = serializers.DictField(help_text="响应头")
diff --git a/src/dashboard/apigateway/apigateway/apis/web/audit/serializers.py b/src/dashboard/apigateway/apigateway/apis/web/audit/serializers.py
@@ -25,11 +25,13 @@
 
 
 class AuditEventLogQueryInputSLZ(serializers.Serializer):
-    time_start = TimestampField(allow_null=True, required=False)
-    time_end = TimestampField(allow_null=True, required=False)
-    op_object_type = serializers.ChoiceField(choices=OpObjectTypeEnum.get_choices(), allow_blank=True, required=False)
-    op_type = serializers.ChoiceField(choices=OP_TYPE_CHOICES, allow_blank=True, required=False)
-    username = serializers.CharField(allow_blank=True, required=False)
+    time_start = TimestampField(allow_null=True, required=False, help_text="开始时间")
+    time_end = TimestampField(allow_null=True, required=False, help_text="结束时间")
+    op_object_type = serializers.ChoiceField(
+        choices=OpObjectTypeEnum.get_choices(), allow_blank=True, required=False, help_text="操作对象类型"
+    )
+    op_type = serializers.ChoiceField(choices=OP_TYPE_CHOICES, allow_blank=True, required=False, help_text="操作类型")
+    username = serializers.CharField(allow_blank=True, required=False, help_text="操作者")
 
 
 class AuditEventLogOutputSLZ(serializers.ModelSerializer):

diff --git a/src/dashboard/apigateway/apigateway/apis/web/metrics/serializers.py b/src/dashboard/apigateway/apigateway/apis/web/metrics/serializers.py
@@ -23,13 +23,15 @@
 
 
 class MetricsQueryInputSLZ(serializers.Serializer):
-    stage_id = serializers.IntegerField(required=True)
-    resource_id = serializers.IntegerField(allow_null=True, required=False)
-    dimension = serializers.ChoiceField(choices=DimensionEnum.get_choices())
-    metrics = serializers.ChoiceField(choices=MetricsEnum.get_choices())
-    time_range = serializers.IntegerField(required=False, min_value=0)
-    time_start = serializers.IntegerField(required=False, min_value=0)
-    time_end = serializers.IntegerField(required=False, min_value=0)
+    stage_id = serializers.IntegerField(required=True, help_text="环境 id")
+    resource_id = serializers.IntegerField(allow_null=True, required=False, help_text="资源 id")
+    dimension = serializers.ChoiceField(
+        choices=DimensionEnum.get_choices(), help_text="维度：app, resource, all, resource_non200_status"
+    )
+    metrics = serializers.ChoiceField(choices=MetricsEnum.get_choices(), help_text="metric 类型")
+    time_range = serializers.IntegerField(required=False, min_value=0, help_text="时间范围")
+    time_start = serializers.IntegerField(required=False, min_value=0, help_text="开始时间")
+    time_end = serializers.IntegerField(required=False, min_value=0, help_text="结束时间")
 
     def validate(self, data):
         if not (data.get("time_start") and data.get("time_end") or data.get("time_range")):

diff --git a/src/dashboard/apigateway/apigateway/apis/web/monitor/serializers.py b/src/dashboard/apigateway/apigateway/apis/web/monitor/serializers.py
@@ -29,26 +29,29 @@
 
 
 class DetectConfigSLZ(serializers.Serializer):
-    duration = serializers.IntegerField(min_value=1)
-    method = serializers.ChoiceField(choices=DETECT_METHOD_CHOICES)
-    count = serializers.IntegerField(min_value=0)
+    duration = serializers.IntegerField(min_value=1, help_text="持续时间")
+    method = serializers.ChoiceField(choices=DETECT_METHOD_CHOICES, help_text="检测方法")
+    count = serializers.IntegerField(min_value=0, help_text="次数")
 
 
 class ConvergeConfigSLZ(serializers.Serializer):
-    duration = serializers.IntegerField(min_value=0)
+    duration = serializers.IntegerField(min_value=0, help_text="持续时间")
 
 
 class NoticeConfigSLZ(serializers.Serializer):
     notice_way = serializers.ListField(
         child=serializers.ChoiceField(choices=NoticeWayEnum.get_choices()),
+        help_text="通知方式",
     )
     notice_role = serializers.ListField(
         child=serializers.ChoiceField(choices=NoticeRoleEnum.get_choices()),
         allow_empty=True,
+        help_text="通知组",
     )
     notice_extra_receiver = serializers.ListField(
         child=serializers.CharField(),
         allow_empty=True,
+        help_text="其他通知对象",
     )
 
     def validate(self, data):
@@ -58,15 +61,17 @@ def validate(self, data):
 
 
 class AlarmStrategyConfigSLZ(serializers.Serializer):
-    detect_config = DetectConfigSLZ()
-    converge_config = ConvergeConfigSLZ()
-    notice_config = NoticeConfigSLZ()
+    detect_config = DetectConfigSLZ(help_text="检测配置")
+    converge_config = ConvergeConfigSLZ(help_text="收敛配置")
+    notice_config = NoticeConfigSLZ(help_text="通知配置")
 
 
 class AlarmStrategyInputSLZ(serializers.ModelSerializer):
-    gateway = serializers.HiddenField(default=CurrentGatewayDefault())
-    gateway_label_ids = serializers.ListField(child=serializers.IntegerField(), allow_empty=True)
-    config = AlarmStrategyConfigSLZ()
+    gateway = serializers.HiddenField(default=CurrentGatewayDefault(), help_text="网关")
+    gateway_label_ids = serializers.ListField(
+        child=serializers.IntegerField(), allow_empty=True, help_text="网关标签 id 列表"
+    )
+    config = AlarmStrategyConfigSLZ(help_text="告警策略配置")
 
     class Meta:
         model = AlarmStrategy
@@ -95,7 +100,7 @@ def validate_gateway_label_ids(self, value):
 
 
 class AlarmStrategyListOutputSLZ(serializers.ModelSerializer):
-    gateway_labels = serializers.SerializerMethodField()
+    gateway_labels = serializers.SerializerMethodField(help_text="网关标签列表")
 
     class Meta:
         model = AlarmStrategy
@@ -124,14 +129,16 @@ class Meta:
 
 
 class AlarmRecordQueryInputSLZ(serializers.Serializer):
-    time_start = TimestampField(allow_null=True, required=False)
-    time_end = TimestampField(allow_null=True, required=False)
-    alarm_strategy_id = serializers.IntegerField(allow_null=True, required=False)
-    status = serializers.ChoiceField(choices=AlarmStatusEnum.get_choices(), allow_blank=True, required=False)
+    time_start = TimestampField(allow_null=True, required=False, help_text="开始时间")
+    time_end = TimestampField(allow_null=True, required=False, help_text="结束时间")
+    alarm_strategy_id = serializers.IntegerField(allow_null=True, required=False, help_text="告警策略 id")
+    status = serializers.ChoiceField(
+        choices=AlarmStatusEnum.get_choices(), allow_blank=True, required=False, help_text="告警状态"
+    )
 
 
 class AlarmRecordQueryOutputSLZ(serializers.ModelSerializer):
-    alarm_strategy_names = serializers.SerializerMethodField()
+    alarm_strategy_names = serializers.SerializerMethodField(help_text="告警策略名称列表")
 
     class Meta:
         model = AlarmRecord
@@ -150,28 +157,29 @@ def get_alarm_strategy_names(self, obj):
 
 
 class AlarmStrategyQueryInputSLZ(serializers.Serializer):
-    query = serializers.CharField(allow_blank=True, required=False)
-    gateway_label_id = serializers.IntegerField(allow_null=True, required=False)
+    query = serializers.CharField(allow_blank=True, required=False, help_text="查询关键字")
+    gateway_label_id = serializers.IntegerField(allow_null=True, required=False, help_text="网关标签 id")
     order_by = serializers.ChoiceField(
         choices=["name", "-name", "updated_time", "-updated_time"],
         allow_blank=True,
         required=False,
+        help_text="排序字段",
     )
 
 
 class AlarmRecordSummaryQueryInputSLZ(serializers.Serializer):
-    time_start = TimestampField(allow_null=True, required=False)
-    time_end = TimestampField(allow_null=True, required=False)
+    time_start = TimestampField(allow_null=True, required=False, help_text="开始时间")
+    time_end = TimestampField(allow_null=True, required=False, help_text="结束时间")
 
 
 class AlarmStrategySummaryQuerySLZ(serializers.Serializer):
-    id = serializers.IntegerField(read_only=True)
-    name = serializers.CharField(read_only=True)
-    alarm_record_count = serializers.IntegerField(read_only=True)
-    latest_alarm_record = serializers.DictField(read_only=True)
+    id = serializers.IntegerField(read_only=True, help_text="策略 id")
+    name = serializers.CharField(read_only=True, help_text="策略名称")
+    alarm_record_count = serializers.IntegerField(read_only=True, help_text="告警记录总数")
+    latest_alarm_record = serializers.DictField(read_only=True, help_text="最新告警记录")
 
 
 class AlarmRecordSummaryQueryOutputSLZ(serializers.Serializer):
-    gateway = serializers.DictField(read_only=True)
-    alarm_record_count = serializers.IntegerField(read_only=True)
-    strategy_summary = serializers.ListField(child=AlarmStrategySummaryQuerySLZ(), read_only=True)
+    gateway = serializers.DictField(read_only=True, help_text="网关")
+    alarm_record_count = serializers.IntegerField(read_only=True, help_text="告警记录总数")
+    strategy_summary = serializers.ListField(child=AlarmStrategySummaryQuerySLZ(), read_only=True, help_text="策略汇总")