Grouping APIs by tags in Spring Boot - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

How does tagging affect API grouping in Spring Boot?

Consider a Spring Boot REST API project using Swagger/OpenAPI annotations. If you assign different @Tag annotations to controller classes, what is the effect on the generated API documentation?

Spring Boot

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

@Tag(name = "User Management")
@RestController
public class UserController {
    @GetMapping("/users")
    public String getUsers() {
        return "List of users";
    }
}

@Tag(name = "Product Management")
@RestController
public class ProductController {
    @GetMapping("/products")
    public String getProducts() {
        return "List of products";
    }
}

A The APIs are grouped under separate sections named 'User Management' and 'Product Management' in the Swagger UI.

B The APIs are merged into a single group ignoring the tags, so all endpoints appear together.

C The tags cause a runtime error when starting the Spring Boot application.

D The tags only affect the Java package structure but not the API documentation.

💡 Hint

Think about how Swagger UI organizes endpoints visually when tags are used.

Using @Tag annotations on controllers groups the APIs in the generated Swagger UI under those tag names, making it easier to navigate related endpoints.

📝 Syntax

intermediate

Identify the correct way to tag a Spring Boot API method

Which of the following code snippets correctly applies a tag to a single API method in Spring Boot using OpenAPI annotations?

A

@Tag("Orders")
@GetMapping("/orders")
public List<Order> getOrders() { return List.of(); }

B

@Tag(name = "Orders")
@GetMapping("/orders")
public List<Order> getOrders() { return List.of(); }

C

@Tags({@Tag(name = "Orders")})
@GetMapping("/orders")
public List<Order> getOrders() { return List.of(); }

D

@Operation(tags = {"Orders"})
@GetMapping("/orders")
public List<Order> getOrders() { return List.of(); }

💡 Hint

Remember that @Tag is for classes, while @Operation can tag methods.

The @Operation annotation has a tags attribute to assign tags to individual API methods. The other options misuse @Tag or its syntax.

🔧 Debug

advanced

Why does this API tag not appear in Swagger UI?

Given the following controller, the tag 'Inventory' does not show in Swagger UI. What is the most likely cause?

Spring Boot

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

@RestController
@Tag(name = "Inventory")
public class InventoryController {
    @GetMapping("/inventory")
    public String getInventory() {
        return "Inventory list";
    }
}

A The @Tag annotation is placed on the class but the OpenAPI configuration does not scan this package.

B The @Tag annotation requires a description attribute to show in Swagger UI.

C The @Tag annotation must be placed on each method, not the class.

D The @RestController annotation is missing, so the controller is not detected.

💡 Hint

Check if the package containing the controller is included in the OpenAPI scan.

If the OpenAPI configuration does not scan the package where the controller is, the tags and endpoints won't appear in Swagger UI even if annotated correctly.

❓ state_output

advanced

What is the effect of multiple tags on a single API method?

Consider this Spring Boot API method annotated with multiple tags. What will be the grouping behavior in Swagger UI?

Spring Boot

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

@RestController
public class MultiTagController {
    @Operation(tags = {"Payments", "Transactions"})
    @GetMapping("/payments")
    public String getPayments() {
        return "Payments data";
    }
}

A The endpoint does not appear in Swagger UI due to multiple tags.

B The endpoint appears only under the first tag 'Payments' and ignores the second.

C The endpoint appears under both 'Payments' and 'Transactions' groups in Swagger UI.

D The endpoint appears under a combined tag named 'Payments, Transactions'.

💡 Hint

Think about how Swagger UI handles multiple tags on one endpoint.

Swagger UI lists the endpoint under each tag specified, so it will show in both 'Payments' and 'Transactions' groups.

🧠 Conceptual

expert

Why use tags to group APIs in Spring Boot projects?

Which of the following is the best explanation for why developers use tags to group APIs in Spring Boot projects with Swagger/OpenAPI?

A Tags automatically generate security rules for each group, enforcing access control without extra configuration.

B Tags improve API documentation readability by logically grouping related endpoints, making it easier for users to find and understand APIs.

C Tags reduce the size of the generated API documentation by hiding untagged endpoints.

D Tags are required by Spring Boot to enable REST controllers to function properly.

💡 Hint

Consider the user experience of API consumers reading the documentation.

Tags are used to organize APIs into meaningful groups in the documentation, improving clarity and navigation. They do not affect security or controller functionality directly.

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