Swagger 3和SpringMVC如何描述POJO RequestParams

Question

我有一个简单的SpringMVC控制器

@RestController
@Validated
@RequestMapping("/users")
public class UsersController {
@GetMapping
public String getAllUsers(@Valid Filter filter) throws MyCustomServiceException {
[...]
}
}

因为这个端点有大约20个RequestParam，而不是用所有的字段来膨胀控制器，我把它们都很好地放在POJO中(实际上可以在需要类似查询参数过滤器的其他控制器中重用)

public class UserFilter extends GenericRequestParams {
[...] 
private String email;
[...] 
}

现在的问题是，Swagger不认为UserFilter和它的字段是查询参数，而是一个简单的对象，所以在Swagger UI上它变得无用，因为很难测试那个端点。

是否有一种方法可以指示swagger,UserFilter字段需要被视为查询参数?

Answer 1

Magic annotation是@ParameterObject

@GetMapping
public String getAllUsers(@Valid @ParameterObject Filter filter) throws MyCustomServiceException {
[...]
}

Answer 2

你可以在你的模型类中使用@ApiParam注释，用@ModelAttribute注释，这样swagger就会在UI中生成这个字段。

public class UserFilter {
@ApiParam(value = "the user email", required = true)
private String email;
}