Swagger 3 and SpringMVC how to describe POJO RequestParams

Question

I have a simple SpringMVC controller

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

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

Since this endpoint has around 20 RequestParam instead of bloating the controller(s) with all the fields I have put them all nicely in a POJO (that actually can be reused in other controllers that needs similar query params filters)

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

Now the problem is that Swagger doesn't consider that UserFilter and its fields to be query params but a simple Object so on the Swagger UI it become useless since it's hard to test that endpoint.

Is there a way to instruct swagger that UserFilter fields needs to be considered query params?

Answer 1

Magic annotation is @ParameterObject

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

Answer 2

You can use @ApiParam annotation in your model class annotated with @ModelAttribute so swagger generates this field into the UI.

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