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

Question

我正在使用 SpringFox 为我的 REST API 生成 swagger 文档。

我现在向我的 API 添加了一个可选参数：

@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);
}

如何在 swagger 文档中突出显示一个是必需的而另一个是可选的？

Answer 1

您可以使用@ApiParam 注释，它有一个属性required，您可以根据需要将其放入true 或false

@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);
}

正如您在documentation 中看到的，它还有其他属性，例如

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