是否可为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
相关产品推荐
相关产品推荐

