Upgrading SpringFox Swagger2 to SpringDoc Openapi (swagger3) annotations

Question

The documentation for migrating to SpringDoc from Swagger2/SpringFox does not address how to convert response and responseContainer fields on @ApiOperation to the new @Operation annotation. How do I do this?

Answer 1

Before converting to SpringDoc, I was using response and responseContainer in SpringFox Swagger 2 to explicitly declare, for example, response="MyResponseDto.class" and responseContainer="List" in order to ensure that all MyResponseDto 's properties and containing collection(s) were properly displayed in the Responses section of the documentation for each API call rather than just "string" or "object" .

SpringDoc handles this all automatically and displays the responses correctly as long as I add the proper typing to the generic for ResponseEntity on my REST controller method signature.

So instead of this:

@GetMapping(value = "/items/{id}")
@Operation(summary = "Get items for component", description = "Retrieves all items for the component by the supplied id")
public ResponseEntity updateMapItem(@PathVariable String id) {
    return new ResponseEntity<>(myService.getItemsForComponent(id), HttpStatus.OK);
}

Use this:

@GetMapping(value = "/items/{id}")
@Operation(summary = "Get items for component", description = "Retrieves all items for the component by the supplied id")
public ResponseEntity<List<MyResponseDto>> updateMapItem(@PathVariable String id) {
    return new ResponseEntity<>(myService.getItemsForComponent(id), HttpStatus.OK);
}

Therefore, response="" and responseContainer="" are no longer necessary.