Spring Boot - @Operation vs @ApiResponse in Swagger

Swagger is a powerful tool for documenting APIs in a standardized way. It allows developers to describe the structure of their APIs so that both machines and humans can understand and interact with them effectively. In the context of Swagger and OpenAPI, annotations play a crucial role in defining how APIs should be documented. Two important annotations are "@Operation" and "@ApiResponse". Understanding the difference and appropriate usage of these annotations is key to creating clear and informative API documentation.

In this article, we will learn @Operation vs @ApiResponse in Swagger.

@Operation Annotation

The @Operation annotation is the part of the io.swagger.v3.oas.annotations package. It can be used to define the operation on a particular API endpoint. It describes the details of the API endpoint such as the summary, description, tags, request parameters, and possible responses. Essentially, it provides a comprehensive overview of what the API operation does.

@ApiResponse Annotation

The @ApiResponse annotation is also part of the io.swagger.v3.oas.annotations package. It can be used to describe the possible responses that the API operation can return. It can be details the status code, the brief description and the content or schema of the responses. @ApiResponse can be often used within the @Operation annotation to specify the different outcomes of the API call.

Difference Between @Operation and @ApiResponse Annotations in Swagger

These differences highlighted how @Operation and @ApiResponse can serve the distinct but complementary roles in the Swagger API documentation.

Example:

@RestController
public class DemoController {

    @Operation(summary = "Greet a user", description = "This endpoint greets the user by name")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Successful greeting"),
            @ApiResponse(responseCode = "400", description = "Bad request - Invalid name provided"),
            @ApiResponse(responseCode = "500", description = "Internal server error")
    })
    @GetMapping("/greet")
    public ResponseEntity<String> greetUser(@RequestParam String name) {
        if (name == null || name.isEmpty()) {
            return ResponseEntity.badRequest().body("Name must not be empty");
        }
        return ResponseEntity.ok("Hello, " + name + "!");
    }
}

Explanation:

• The @Operation annotation can provides the summary and description of the /greet endpoint.
• The @ApiResponses annotation can contains the multiple @ApiResponse annotations, each specifying the possible response code (e.g..,200, 400, 500) and its corresponding description.

Conclusion

The @Operation and @ApiResponse annotation are crucial for the enhancing the API documentation in Swagger. While @Operation provides the high level overview of the API operation, @ApiResponse details the specific responses that the API can return. Together, they can create the comprehensive and informative documentation that improves the both development and the user experience.