Grouping APIs by tags in Spring Boot - Performance & Optimization

Performance: Grouping APIs by tags

MEDIUM IMPACT

This affects the API documentation load time and client-side rendering speed when browsing grouped endpoints.

Organizing API endpoints in documentation for faster client rendering

Spring Boot

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "User management APIs")
public class UserController {
  @GetMapping("")
  public List<User> getUsers() { ... }
  @PostMapping("")
  public User createUser() { ... }
}

@RestController
@RequestMapping("/api/orders")
@Tag(name = "Orders", description = "Order management APIs")
public class OrderController {
  @GetMapping("")
  public List<Order> getOrders() { ... }
}

Endpoints are grouped by tags, so documentation UI renders smaller groups on demand, improving load speed and user navigation.

📈 Performance GainReduces initial DOM nodes rendered, improving LCP and interaction readiness.

Organizing API endpoints in documentation for faster client rendering

Spring Boot

@RestController
@RequestMapping("/api")
public class UserController {
  @GetMapping("/users")
  public List<User> getUsers() { ... }
  @PostMapping("/users")
  public User createUser() { ... }
  @GetMapping("/orders")
  public List<Order> getOrders() { ... }
}

All endpoints are in one controller without tags, causing documentation UI to render a long flat list, slowing initial load and navigation.

📉 Performance CostDocumentation UI triggers rendering of all endpoints at once, increasing LCP and blocking user interaction.

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Flat list of all endpoints	High number of DOM nodes	Multiple reflows due to large layout	High paint cost from many elements	[X] Bad
Grouped endpoints by tags	Fewer DOM nodes initially	Single reflow per group expansion	Lower paint cost with smaller visible sets	[OK] Good

Rendering Pipeline

Grouping APIs by tags reduces the number of DOM nodes rendered initially by the documentation UI, lowering the cost in style calculation, layout, and paint stages.

→DOM Construction

→Style Calculation

→Layout

→Paint

⚠️ BottleneckLayout and Paint stages due to large flat lists of endpoints

Core Web Vital Affected

LCP

This affects the API documentation load time and client-side rendering speed when browsing grouped endpoints.

Optimization Tips

1Group API endpoints by tags to reduce initial DOM size in documentation UI.

2Avoid rendering all endpoints at once to prevent layout thrashing and slow paint.

3Use lazy loading or collapsible groups to improve user interaction speed.

Performance Quiz - 3 Questions

How does grouping APIs by tags affect the documentation page's Largest Contentful Paint (LCP)?

A It reduces LCP by limiting initial DOM nodes rendered

B It increases LCP by adding extra grouping elements

C It has no effect on LCP

D It only affects interaction speed, not LCP

DevTools: Performance

How to check: Record a performance profile while opening the API documentation page and expanding groups. Observe the flame chart for layout and paint times.

What to look for: Look for long layout and paint tasks when all endpoints render at once versus shorter tasks when grouped and lazily loaded.

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