字段说明获取

.gitea/checker/controller_ast_parser.py

@@ -233,6 +233,27 @@ def _param_required(param: FormalParameter) -> bool:
     return not _has_ann(param, "Nullable")
 
 
+def _param_description(param: FormalParameter) -> Optional[str]:
+    """提取参数描述，优先 Swagger 注解，其次 @RequestParam 的 value。"""
+    # 1. Swagger @ApiParam
+    ann = _find_ann(param, "ApiParam")
+    if ann:
+        desc = _ann_string(ann, "value", "name")
+        if desc:
+            return desc
+
+    # 2. Swagger @ApiImplicitParam（方法级注解，较少见，暂不实现）
+
+    # 3. Fallback: @RequestParam 的 value 作为描述提示
+    ann = _find_ann(param, "RequestParam")
+    if ann:
+        val = _ann_string(ann, "value", "name")
+        if val and val != param.name:
+            return val
+
+    return None
+
+
 class ControllerAstParser:
     """
     基于 javalang 的 Controller 解析器。
@@ -325,12 +346,14 @@ class ControllerAstParser:
         if _has_ann(param, "RequestBody"):
             return self._expand_dto(type_name, "body")
 
+        desc = _param_description(param)
         return [
             ApiParameter(
                 name=name,
                 type=type_name,
                 required=_param_required(param),
                 source=_param_source(param),
+                description=desc,
             )
         ]
 
@@ -361,12 +384,19 @@ class ControllerAstParser:
                 if "static" in (field.modifiers or []):
                     continue
                 for decl in field.declarators:
+                    # 尝试提取 @ApiModelProperty 的描述
+                    desc = None
+                    api_model_ann = _find_ann(field, "ApiModelProperty")
+                    if api_model_ann:
+                        desc = _ann_string(api_model_ann, "value")
+
                     fields.append(
                         ApiParameter(
                             name=decl.name,
                             type=_type_to_str(field.type),
                             required=not _has_ann(field, "Nullable"),
                             source=source,
+                            description=desc,
                         )
                     )