Grouping APIs by tags in Spring Boot - Mini Project: Build & Apply

Grouping APIs by tags in Spring Boot

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to organize your API endpoints by grouping them with tags for better documentation and clarity.

🎯 Goal: Create a Spring Boot controller with two API endpoints grouped by tags using @Tag annotations from OpenAPI. This will help organize the API documentation by categories like 'Books' and 'Authors'.

📋 What You'll Learn

Create a Spring Boot controller class named BookstoreController.

Add two API endpoints: /books and /authors.

Use @Tag annotations to group /books under the tag 'Books' and /authors under the tag 'Authors'.

Use @GetMapping for both endpoints returning simple string messages.

💡 Why This Matters

🌍 Real World

Grouping APIs by tags helps organize large REST APIs, making documentation clearer and easier to navigate for developers and users.

💼 Career

Understanding how to group APIs by tags is important for backend developers working with Spring Boot and OpenAPI to create well-documented and maintainable APIs.

1

Create the controller class with the /books endpoint

Create a Spring Boot controller class named BookstoreController annotated with @RestController. Inside it, create a method named getBooks mapped to /books using @GetMapping that returns the string "List of books".

Spring Boot

@RestController
public class BookstoreController {
    // Your code here
}

Hint

Use @RestController on the class and @GetMapping("/books") on the method.

2

Add a /authors endpoint method

Inside the BookstoreController class, add a method named getAuthors mapped to /authors using @GetMapping that returns the string "List of authors".

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BookstoreController {
    @GetMapping("/books")
    public String getBooks() {
        return "List of books";
    }

    // Your code here
}

Hint

Add a new method with @GetMapping("/authors") that returns the string "List of authors".

3

Import and add @Tag annotations for grouping

Import io.swagger.v3.oas.annotations.tags.Tag and add @Tag(name = "Books") above the getBooks method and @Tag(name = "Authors") above the getAuthors method to group the endpoints by tags.

Spring Boot

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

@RestController
public class BookstoreController {
    @GetMapping("/books")
    // Your code here
    public String getBooks() {
        return "List of books";
    }

    @GetMapping("/authors")
    // Your code here
    public String getAuthors() {
        return "List of authors";
    }
}

Hint

Use @Tag(name = "Books") and @Tag(name = "Authors") annotations above the respective methods.

4

Add class-level @Tag annotation for overall grouping

Add a class-level @Tag(name = "Bookstore API") annotation above the BookstoreController class to group all endpoints under a main tag.

Spring Boot

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

// Your code here
@RestController
public class BookstoreController {
    @Tag(name = "Books")
    @GetMapping("/books")
    public String getBooks() {
        return "List of books";
    }

    @Tag(name = "Authors")
    @GetMapping("/authors")
    public String getAuthors() {
        return "List of authors";
    }
}

Hint

Place @Tag(name = "Bookstore API") above the class declaration.

Practice

1. What is the main purpose of using @Tag annotation in Spring Boot controllers?

easy

A. To specify the database table for the API

B. To group related APIs for better documentation organization

C. To define the HTTP method of an API endpoint

D. To secure APIs with authentication

Solution

1. Step 1: Understand the role of @Tag

   The @Tag annotation is used to group APIs logically in documentation tools like Swagger.

2. Step 2: Identify its effect on API docs

   Grouping APIs by tags makes the documentation easier to read and navigate for users.

3. Final Answer:

   To group related APIs for better documentation organization -> Option B

4. Quick Check:

   @Tag groups APIs = D [OK]

Hint: Remember @Tag groups APIs for docs, not for security or DB [OK]

Common Mistakes:

• Confusing @Tag with security annotations
• Thinking @Tag sets HTTP methods
• Assuming @Tag relates to database mapping

2. Which of the following is the correct way to add a tag named "User Management" to a Spring Boot controller?

easy

A. @Tag(name = "User Management") above the controller class

B. @Tag(value = "User Management") above each method

C. @Tag("User Management") inside the method body

D. @Tag(name = "User Management") inside the application.properties file

Solution

1. Step 1: Identify correct @Tag usage

   The @Tag annotation is placed above the controller class with the name attribute to specify the tag.

2. Step 2: Confirm placement and syntax

   It should not be inside methods or properties files; it applies at the class level for grouping all endpoints.

3. Final Answer:

   @Tag(name = "User Management") above the controller class -> Option A

4. Quick Check:

   @Tag(name=...) on class = A [OK]

Hint: Place @Tag(name=...) above controller class, not methods or config [OK]

Common Mistakes:

• Using @Tag inside method bodies
• Using 'value' instead of 'name' attribute
• Placing @Tag in properties files

3. Given this controller code snippet:

@RestController
@Tag(name = "Orders")
public class OrderController {
  @GetMapping("/orders")
  public List<String> getOrders() { return List.of("order1", "order2"); }
}

What tag will appear in the generated API documentation for the /orders endpoint?

medium

A. "Orders"

B. No tag will appear

C. "OrderController"

D. "getOrders"

Solution

1. Step 1: Check @Tag annotation on controller

   The controller class has @Tag(name = "Orders"), so all its endpoints inherit this tag.

2. Step 2: Determine tag shown in docs

   The /orders endpoint will be grouped under the "Orders" tag in the API documentation.

3. Final Answer:

   "Orders" -> Option A

4. Quick Check:

   Controller @Tag name = "Orders" means tag = B [OK]

Hint: Controller-level @Tag sets tag for all its endpoints [OK]

Common Mistakes:

• Expecting method name as tag
• Thinking no tag appears without method-level @Tag
• Confusing class name with tag

4. Consider this controller code:

@RestController
@Tag(name = "Products")
public class ProductController {
  @GetMapping("/products")
  public List<String> getProducts() { return List.of("prod1", "prod2"); }

  @Tag(name = "Special")
  @GetMapping("/products/special")
  public List<String> getSpecialProducts() { return List.of("special1"); }
}

What is the problem with this code regarding API grouping by tags?

medium

A. Multiple @Tag annotations cause runtime errors

B. Method-level @Tag overrides class-level @Tag correctly

C. @Tag cannot be used on methods, causing a compile error

D. Method-level @Tag is ignored; only class-level @Tag works

Solution

1. Step 1: Check @Tag usage rules

   In Spring Boot with OpenAPI, @Tag is primarily for class-level use to group endpoints. Method-level @Tag is ignored for grouping purposes.

2. Step 2: Identify its effect on API docs

   The /products/special endpoint will still be grouped under the "Products" tag, as method-level @Tag does not override class-level grouping.

3. Final Answer:

   Method-level @Tag is ignored; only class-level @Tag works -> Option D

4. Quick Check:

   Method-level @Tag ignored = A [OK]

Hint: Use @Tag only on controller classes, not on methods [OK]

Common Mistakes:

• Assuming method-level @Tag overrides class-level
• Thinking multiple @Tag annotations cause runtime errors
• Ignoring that method-level @Tag is invalid

5. You have two controllers:

@RestController
@Tag(name = "Users")
public class UserController {
  @GetMapping("/users")
  public List<String> getUsers() { return List.of("user1", "user2"); }
}

@RestController
@Tag(name = "Admins")
public class AdminController {
  @GetMapping("/admins")
  public List<String> getAdmins() { return List.of("admin1"); }
}

How will the API documentation group these endpoints?

hard

A. No tags will appear in the documentation

B. All endpoints under a single "Users" tag

C. Endpoints grouped separately under "Users" and "Admins" tags

D. Endpoints grouped under controller class names as tags

Solution

1. Step 1: Identify tags on each controller

   UserController has @Tag(name = "Users") and AdminController has @Tag(name = "Admins").

2. Step 2: Understand grouping in docs

   Each controller's endpoints are grouped under their respective tags in the API docs.

3. Final Answer:

   Endpoints grouped separately under "Users" and "Admins" tags -> Option C

4. Quick Check:

   Separate @Tag names create separate groups = A [OK]

Hint: Different @Tag names on controllers create separate groups [OK]

Common Mistakes:

• Assuming all endpoints merge under one tag
• Expecting no tags without method-level @Tag
• Thinking controller class names become tags automatically