@Operation annotation for descriptions in Spring Boot

Introduction

The @Operation annotation helps add clear descriptions to your API endpoints. This makes your API easier to understand for others.

You want to explain what an API endpoint does in your Spring Boot project.

You need to generate API documentation automatically with tools like Swagger or OpenAPI.

You want to provide extra details like summary or notes for your REST controllers.

You want to improve communication between backend developers and frontend or API users.

Syntax

Spring Boot

@Operation(summary = "Short summary", description = "Detailed explanation")

Use summary for a brief explanation.

Use description for more detailed info.

Examples

Adds a short summary to the API method.

Spring Boot

@Operation(summary = "Get all users")

Adds both summary and detailed description.

Spring Boot

@Operation(summary = "Create user", description = "Adds a new user to the database.")

Adds only a detailed description without summary.

Spring Boot

@Operation(description = "Deletes a user by ID.")

Sample Program

This Spring Boot controller has one endpoint /users. The @Operation annotation adds a summary and description for API documentation tools.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;

@RestController
public class UserController {

    @GetMapping("/users")
    @Operation(summary = "List all users", description = "Returns a list of all registered users in the system.")
    public String getUsers() {
        return "User list";
    }
}

Important Notes

The @Operation annotation is part of the OpenAPI/Swagger specification integration.

It does not change how your API works, only how it is documented.

Make sure to include the OpenAPI dependency in your project to use @Operation.

Summary

@Operation adds clear descriptions to API endpoints.

Use summary for short info and description for details.

This helps generate easy-to-understand API docs automatically.