Grouping APIs by tags in Spring Boot - Step-by-Step Execution

Concept Flow - Grouping APIs by tags

Define API Controller

↓

Add Tag Annotation

↓

Define API Endpoints

↓

Run Application

↓

API Docs Show Grouped Tags

↓

User Sees APIs Grouped by Tags

This flow shows how adding tags to API controllers groups endpoints in documentation tools like Swagger.

Execution Sample

Spring Boot

@Tag(name = "User")
@RestController
@RequestMapping("/users")
public class UserController {
  @GetMapping
  public List<User> getAll() { return List.of(); }
}

This code defines a User API controller tagged as 'User' to group its endpoints.

Execution Table

Step	Action	Annotation Processed	Effect on API Docs	Output
1	Start application	No tags processed yet	No grouping in docs	API docs show all endpoints ungrouped
2	Read @Tag(name = "User") on UserController	Tag 'User' assigned	Endpoints under UserController grouped under 'User'	User endpoints grouped in docs
3	Read @GetMapping on getAll()	Endpoint registered	Endpoint appears under 'User' tag	GET /users listed under 'User'
4	Application running	Tags and endpoints loaded	Grouping visible in Swagger UI	User tag with GET /users endpoint shown
5	User views docs	Tags used for grouping	Easier navigation by tag	User sees APIs grouped by tags

💡 Application fully started with API endpoints grouped by tags for documentation.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
tags	[]	["User"]	["User"]	["User"]	["User"]
endpoints	[]	[]	["GET /users"]	["GET /users"]	["GET /users"]
apiDocsGrouping	None	Partial	Partial	Complete	Complete

Key Moments - 2 Insights

Why do APIs appear grouped under tags in documentation?

Because the @Tag annotation assigns a name to the controller or endpoint, which documentation tools use to group APIs. See execution_table step 2 and 4.

What happens if no @Tag annotation is added?

APIs appear ungrouped or under a default group in docs, making navigation harder. This is shown in execution_table step 1.

Visual Quiz - 3 Questions

Look at the execution_table at step 3, what endpoint is registered under the 'User' tag?

A DELETE /users

B POST /users

C GET /users

D PUT /users

💡 Hint

Check the 'Output' column at step 3 in execution_table.

At which step does the API documentation show grouping by tags?

A Step 4

B Step 1

C Step 2

D Step 5

💡 Hint

Look at the 'Effect on API Docs' column for when grouping is complete.

If you remove the @Tag annotation, how does the variable 'tags' change after step 2?

A It contains 'User'

B It becomes empty []

C It contains multiple tags

D It causes an error

💡 Hint

Refer to variable_tracker 'tags' value after step 2.

Concept Snapshot

Use @Tag(name = "TagName") on controllers or methods.
This groups APIs in documentation tools like Swagger.
Without tags, APIs appear ungrouped.
Tags improve API navigation and clarity.
Run app to see grouping in Swagger UI.

Full Transcript

Grouping APIs by tags in Spring Boot means adding the @Tag annotation to your API controllers or methods. This annotation assigns a name that documentation tools like Swagger use to group your endpoints. When the application starts, it reads these tags and organizes the API docs accordingly. Without tags, all APIs appear in one list, which can be confusing. Adding tags helps users find related APIs easily. For example, a UserController with @Tag(name = "User") will have all its endpoints grouped under 'User' in the docs. This process happens during app startup and is visible in the Swagger UI.

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