Grouping Endpoints by Resources in Swagger

1. Introduction

In this tutorial, we’ll explore the Swagger documenting feature in Java. Specifically, we’ll be focusing on how to organize our project’s APIs based on their URLs.

There are several methods to achieve this resource grouping. However, for this discussion, we’ll concentrate on the @Tag annotation, which is typically applied on top of our controllers.

2. Understanding Swagger and the @Tag Annotation

Swagger is a really handy open-source framework that helps us design, build, document, and test our REST APIs. Primarily, it’s auto-generated, ensuring consistently up-to-date documentation that’s always in sync with our API.

Within the context of Swagger (OpenAPI), tags serve as a crucial mechanism for grouping and categorizing our API operations. Specifically, they provide a robust method for organizing our API documentation to enhance its clarity and usability.

Now, it’s important to note that tags can be defined at either the class or function level within our controller classes. Consequently, each operation, be it a GET, POST, PUT, or DELETE request, can be associated with one or more tags.

Furthermore, Swagger UIs typically render these tags as collapsible sections or categories, allowing for easy navigation and comprehension.

Therefore, by leveraging tags effectively, we can significantly improve the structure and accessibility of our API documentation.

3. Setting up the Spring Boot Project

Before getting started with Swagger, we need a Spring Boot project with some APIs.

To begin, we’ll navigate to the Spring Initializer. Subsequently, we’ll configure our project using the following parameters:

• Project: Maven
• Language: Java
• Spring Boot Version: 3.4.4 (or any stable release)
• Group: com.swaggertags
• Artifact: demo
• Description: Demo project for Swagger tags
• Packaging: Jar
• JDK: 17

Following this, we click the Generate button to download our project. Once the project archive is downloaded, we can extract its contents.

Next, let’s add the necessary dependencies to our project’s configuration file.

3.1. Adding Maven Dependencies

We need a controller to demo our grouping of resources. So, let’s add a web starter dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

It brings in all the necessary components for creating RESTful APIs, web pages, and other web-based functionalities.

Now, let’s add the Swagger dependency to get started with Swagger:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.4.0</version>
</dependency>

This dependency adds Swagger/OpenAPI support to our Spring Boot Web MVC application, along with a user-friendly interface.

4. Creating Controller Classes With Swagger @Tag Annotation

Let’s create UserController, which has all the user-related operations with the URLs starting with “/api/users/“:

@RestController
@RequestMapping("/api/users/")
@Tag(name = "User Management", description = "Operations related to users")
public class UserController {

    @PostMapping("login")
    public ResponseEntity<String> userLogin() {
        return ResponseEntity.ok("Logged In");
    }

    @Tag(name = "dashboard")
    @GetMapping("profile")
    public ResponseEntity<String> getUserProfile() {
        return ResponseEntity.ok("User Profile");
    }

    @Tag(name = "dashboard")
    @GetMapping("orders")
    public ResponseEntity<String> getUserOrders() {
        return ResponseEntity.ok("User Orders");
    }
}

Let’s understand the annotations above the class.

The @RestController annotation tells Spring that the class is a REST controller, meaning it handles HTTP requests and returns responses in a RESTful manner. The @RequestMapping(“/api/users/”) annotation sets the base URL path for all the methods within the controller, helping to organize and group related endpoints.

Additionally, the @Tag annotation, which comes from the SpringDoc (Swagger/OpenAPI) library, is used to group related API endpoints in the generated Swagger documentation. The name attribute (e.g., “User Management“) creates a category in the Swagger UI, while the description attribute (e.g., “Operations related to users“) adds helpful context to make the category more understandable.

We can also use the @Tag annotation on individual methods, such as getUserOrders(), to categorize specific endpoints.

Let’s also create one more controller named OrderController with all the order-related operations, and the URLs for this start with “/api/orders”:

@RestController
@RequestMapping("/api/orders")
@Tag(name = "Order Management", description = "Operations related to orders")
public class OrderController {

    @GetMapping
    public ResponseEntity<String> getAllOrders() {
        return ResponseEntity.ok("Order 1");
    }

}

Again, we have the same @Tag annotation to group the related API with the same prefixes. But, this time, the name and description are different as it’ll result in a different group.

4.1. Output

Now we can run our application and go to the URL “http://localhost:8080/swagger-ui/index.html” which represents the default Swagger UI URL.

We see two groups and the endpoints related to them inside them as we expand:

5. Conclusion

In this article, we saw how Swagger (now part of the OpenAPI specification) is a powerful tool that simplifies designing, documenting, and testing REST APIs. It auto-generates real-time, interactive API documentation, reducing manual effort and keeping our docs always in sync with our code.

The @Tag annotation from springdoc-openapi is essential for API organization in Spring Boot. By applying @Tag at the class or method level, we can group related endpoints—such as user and order operations—into distinct, collapsible sections in the Swagger UI. This improves readability, structure, and collaboration for developers.

With minimal setup (adding a few Maven dependencies and controller annotations), we get a well-organized Swagger UI where our APIs are clearly grouped and easy to navigate. This enhances developer experience, especially in larger applications.

As always, the code for this article is available over on GitHub.