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
}

Need a 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
}

Need a 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";
    }
}

Need a 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";
    }
}

Need a hint?

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