Grouping APIs by tags in Spring Boot

Introduction

Grouping APIs by tags helps organize your endpoints clearly. It makes your API easier to understand and use.

You want to separate user-related APIs from product-related APIs.

You need to show different API groups in your documentation.

You want to make it easier for developers to find specific API endpoints.

You are building a large API with many endpoints and want better structure.

Syntax

Spring Boot

@Tag(name = "tagName", description = "Description of this group")
@RestController
@RequestMapping("/api/path")
public class YourController {
    // API methods
}

Use @Tag on your controller class to group all its APIs under one tag.

The name attribute is the tag name shown in API docs like Swagger UI.

Examples

This groups all user-related APIs under the 'Users' tag.

Spring Boot

@Tag(name = "Users", description = "Operations about users")
@RestController
@RequestMapping("/users")
public class UserController {
    // user APIs
}

This groups all product-related APIs under the 'Products' tag.

Spring Boot

@Tag(name = "Products", description = "Manage products")
@RestController
@RequestMapping("/products")
public class ProductController {
    // product APIs
}

Sample Program

This Spring Boot controller groups its API under the 'Books' tag. When you generate API docs (like Swagger UI), this tag helps organize the endpoint.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Books", description = "Operations related to books")
@RestController
@RequestMapping("/books")
public class BookController {

    @GetMapping
    public String listBooks() {
        return "List of books";
    }
}

Important Notes

Make sure to add the OpenAPI/Swagger dependency to your project to use @Tag annotations effectively.

Tags improve API documentation but do not affect the API behavior itself.

Summary

Use @Tag to group related APIs in your Spring Boot controllers.

Tags help organize and clarify your API documentation.

Each controller can have one or more tags describing its purpose.