Swagger 3和SpringMVC如何描述Pojo RequestParams

Question

我有一个简单的SpringMVC控制器

@RestController
@Validated
@RequestMapping("/users")
public class UsersController {

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

，因为该端点具有约20个请求Param，而不是用所有的字段将它们都放在POJO中的所有字段（实际上可以在需要类似的查询参数过滤器的其他控制器中重复使用），而不是将控制器膨胀。

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

现在的问题是，Swagger不认为userFilter及其字段是查询参数，而是一个简单的对象，因此在Swagger UI上，它变得毫无用处，因为很难测试该端点。

有没有办法指示Swagger UserFilter字段需要视为查询参数？

Answer 1

魔术注释是@parameterObject

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

Answer 2

您可以在用@modelattribute注释的模型类中使用@apiparam注释，因此Swagger将此字段生成UI。

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