如何让Springfox Swagger为GET接口的复杂嵌套对象生成API文档？

我之前也碰到过一模一样的问题，Springfox 2.9.2对GET请求里的嵌套DTO参数支持确实有点“迟钝”——它默认不会自动解析嵌套对象里的属性，只会把整个DTO当成一个模糊的参数展示。不过有几个靠谱的办法能搞定：

方法一：添加@ModelAttribute注解+@ApiModelProperty注解（推荐） #

这是最简洁且自动的方案，两步就能解决：

1. 给Controller接口的DTO参数加上@ModelAttribute
   告诉Spring MVC和Springfox，这个参数是要解析为请求查询参数的模型对象，而不是一个单一参数：

   @GetMapping("/search")
   public Something search(@ModelAttribute SearchDTO input) { }
   

2. 给DTO的所有嵌套字段添加@ApiModelProperty注解
   明确每个字段的含义，同时让Springfox识别到这些嵌套属性：

   public class SearchDTO { 
       @ApiModelProperty(value = "过滤条件集合")
       private SearchFilterDto filters; 
       @ApiModelProperty(value = "分页配置")
       private Page page; 
       @ApiModelProperty(value = "排序规则")
       private Sort sort; 
   }
   
   public class SearchFilterDto { 
       @ApiModelProperty(value = "按名称模糊匹配")
       private String name; 
   }
   

   记得确保所有DTO都有无参构造函数和完整的getter/setter——这是Spring MVC解析参数和Springfox生成文档的前提。

这样配置后，Swagger文档里就会展开所有嵌套的参数，比如filters.name、page.pageNumber这类查询参数，每个参数都会带上你定义的描述。

方法二：手动用@ApiImplicitParams定义参数（适合字段少的场景） #

如果不想给所有字段加注解，或者只需要展示部分嵌套参数，可以手动声明每个查询参数：

@GetMapping("/search")
@ApiImplicitParams({
    @ApiImplicitParam(name = "filters.name", value = "按名称模糊匹配", dataType = "string", paramType = "query"),
    @ApiImplicitParam(name = "page.page", value = "当前页码", dataType = "int", paramType = "query"),
    @ApiImplicitParam(name = "sort.field", value = "排序字段", dataType = "string", paramType = "query")
})
public Something search(SearchDTO input) { }

这种方式比较灵活，但如果嵌套字段多的话会很繁琐，维护起来也麻烦，所以更适合简单场景。

注意事项 #

• 如果你试过上面的方法还是不行，检查一下是否有自定义的Swagger配置（比如Docket），确保没有禁用模型属性的解析；
• 2.9.2版本确实存在一些嵌套参数的小bug，如果允许的话，升级到Springfox 3.x版本会有更好的支持，但如果必须用2.9.2，上面的方法足够解决问题。

内容的提问来源于stack exchange，提问作者tzortzik