如何在 Swagger 中将 RequestParam 标记为可选？

Question

I am generating the swagger docs for my REST API using SpringFox.

I have added an optional parameter to my API now:

@ApiOperation(
  value = "Get all cars"
)
@GetMapping(value = "/cars", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<ResponseDTO<CarDTO>> getCars(
  @RequestParam(defaultValue = "1") Integer page,
  @RequestParam(required = false) String status) {
  ResponseDTO<CarDTO> response = service.getCars(page, status);
  return ResponseEntity.ok(response);
}

How do I highlight in the swagger docs that one is required and the other is optional?

Answer 1

You have the @ApiParam annotation you can use, it has a property required which you can put to true or false depending on your needs

@ApiOperation(
  value = "Get all cars"
)
@GetMapping(value = "/cars", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<ResponseDTO<CarDTO>> getCars(
  @ApiParam(required = true) @RequestParam(defaultValue = "1") Integer page,
  @ApiParam(required = false) @RequestParam(required = false) String status) {
  ResponseDTO<CarDTO> response = service.getCars(page, status);
  return ResponseEntity.ok(response);
}

As you can see in the documentation , it has other properties like

• access
• allowableValues
• allowMultiple
• defaultValue
• name
• value