You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

是否可为Swagger接口文档中的请求参数添加自定义描述?

实现方案

完全可以实现,不需要调整接口业务逻辑,只要给对应参数加Swagger的参数描述注解即可。

你当前用的是Swagger3(OpenAPI3)注解体系,直接给fromDate和toDate两个参数加@Parameter注解,在description属性里写清楚查询规则即可,修改后的两个日期参数声明参考:

// 其余参数保持原有写法不变,仅调整from、to两个日期参数
@Parameter(description = "查询起始时间(闭区间):仅返回预约开始时间 ≥ 该值的记录,时间格式要求 yyyy-MM-dd'T'HH:mm:ss")
@RequestParam(required = false, name = "from") 
@DateTimeFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss") 
Date fromDate,

@Parameter(description = "查询结束时间(闭区间):仅返回预约开始时间 ≤ 该值的记录,时间格式要求 yyyy-MM-dd'T'HH:mm:ss")
@RequestParam(required = false, name = "to") 
@DateTimeFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss") 
Date toDate,

补充说明:

  • 注解直接加在方法参数上即可,Swagger启动后会自动把描述文本渲染到对应参数名下方的说明区域
  • 如果你用的是旧版SpringFox(Swagger2),把@Parameter换成@ApiParam即可,属性写法完全一致:@ApiParam(value = "这里写描述内容")
  • 如果你想把范围规则放在接口整体说明中,而不是拆分到两个参数下,也可以直接给方法上的@Operation注解加description属性,示例:
    @Operation(
      summary = "Get the list of appointments",
      description = "查询预约开始时间落在from~to日期范围内的预约记录,传入的日期范围为闭区间"
    )
    

内容的提问来源于stack exchange,提问作者intA

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.08.26 23:30:52