Why API docs matter in Spring Boot - See It in Action

Why API docs matter

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to make sure other developers can easily understand and use your API by adding clear documentation.

🎯 Goal: Create a Spring Boot REST controller with API documentation using OpenAPI annotations. This will help others know what your API does and how to use it.

📋 What You'll Learn

Create a Spring Boot REST controller class named BookController.

Add a GET endpoint /books that returns a list of book titles.

Create a configuration variable apiTitle with the value Bookstore API.

Use OpenAPI annotations to document the API title and the GET endpoint.

Add a final annotation to enable OpenAPI documentation generation.

💡 Why This Matters

🌍 Real World

API documentation is essential in real projects to help teams and external users understand how to interact with your backend services without confusion.

💼 Career

Knowing how to document APIs with OpenAPI is a valuable skill for backend developers, improving collaboration and speeding up development cycles.

1

Create the REST controller with a GET endpoint

Create a Spring Boot REST controller class named BookController with a GET endpoint /books that returns a list of strings: "Spring in Action", "Effective Java", and "Clean Code".

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BookController {
    // Your code here
}

Hint

Use @RestController on the class and @GetMapping("/books") on the method that returns a list of book titles.

2

Add API title configuration

Add a String variable named apiTitle with the value "Bookstore API" inside the BookController class.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RestController
public class BookController {
    // Add apiTitle variable here

    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Hint

Declare a private static final String variable named apiTitle and assign it the value "Bookstore API".

3

Add OpenAPI annotations to document the API

Add the OpenAPI annotation @Tag(name = apiTitle) on the BookController class and @Operation(summary = "Get list of books") on the getBooks method. Import these annotations from io.swagger.v3.oas.annotations.

Spring Boot

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

// Add @Tag annotation here
@RestController
public class BookController {
    private static final String apiTitle = "Bookstore API";

    // Add @Operation annotation here
    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Hint

Use @Tag(name = apiTitle) on the class and @Operation(summary = "Get list of books") on the method.

4

Enable OpenAPI documentation generation

Add the @OpenAPIDefinition annotation on the BookController class with an info property setting the title to apiTitle. Import @OpenAPIDefinition and Info from io.swagger.v3.oas.annotations.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;

// Add @OpenAPIDefinition annotation here
@Tag(name = apiTitle)
@RestController
public class BookController {
    private static final String apiTitle = "Bookstore API";

    @Operation(summary = "Get list of books")
    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Hint

Use @OpenAPIDefinition(info = @Info(title = apiTitle)) on the class to enable API docs.

Practice

1. Why are API documentation tools important in Spring Boot projects?

easy

A. They replace the need for writing any code.

B. They automatically generate clear docs for backend services.

C. They slow down the application performance.

D. They only work with frontend frameworks.

Solution

1. Step 1: Understand the role of API docs

   API docs explain how backend services work and how to use them.

2. Step 2: Recognize automation benefits in Spring Boot

   Tools like Springdoc generate these docs automatically, saving time and reducing errors.

3. Final Answer:

   They automatically generate clear docs for backend services. -> Option B

4. Quick Check:

   API docs help by auto-generating clear service info [OK]

Hint: API docs = clear backend usage + automation [OK]

Common Mistakes:

• Thinking API docs replace coding
• Believing docs slow app performance
• Assuming docs only help frontend

2. Which annotation is commonly used in Spring Boot to enable automatic API documentation generation?

easy

A. @EnableSwagger2

B. @SpringBootApplication

C. @RestController

D. @DocumentedApi

Solution

1. Step 1: Identify the annotation for Swagger integration

   @EnableSwagger2 is used to enable Swagger-based API docs generation in Spring Boot.

2. Step 2: Differentiate from other annotations

   @SpringBootApplication starts the app, @RestController defines controllers, and @DocumentedApi is not a valid Spring Boot annotation.

3. Final Answer:

   @EnableSwagger2 -> Option A

4. Quick Check:

   Swagger docs enabled by @EnableSwagger2 [OK]

Hint: Swagger docs need @EnableSwagger2 annotation [OK]

Common Mistakes:

• Confusing @SpringBootApplication with docs enabling
• Using @RestController for docs generation
• Assuming @DocumentedApi is a real annotation

3. Given this Spring Boot controller snippet with Springdoc enabled, what will the generated API docs show for the endpoint?

@RestController
@RequestMapping("/api")
public class UserController {
  @GetMapping("/users/{id}")
  public User getUser(@PathVariable String id) {
    return new User(id, "Alice");
  }
}

medium

A. An endpoint POST /api/users that creates a new user.

B. An endpoint GET /users without path variables.

C. No endpoint will be documented because @GetMapping is missing.

D. An endpoint GET /api/users/{id} that returns a User object with id and name.

Solution

1. Step 1: Analyze the controller mapping

   The class maps to /api, and the method maps GET requests to /users/{id} with a path variable.

2. Step 2: Understand Springdoc output

   Springdoc generates docs showing GET /api/users/{id} returning a User object with id and name fields.

3. Final Answer:

   An endpoint GET /api/users/{id} that returns a User object with id and name. -> Option D

4. Quick Check:

   GET /api/users/{id} documented with User return [OK]

Hint: Check @RequestMapping + @GetMapping paths for docs URL [OK]

Common Mistakes:

• Confusing GET with POST method
• Ignoring path variables in URL
• Assuming no docs generated without extra config

4. You added Springdoc to your Spring Boot app but the API docs page shows no endpoints. What is the most likely cause?

medium

A. You forgot to add @RestController to your controller classes.

B. You wrote your endpoints in XML configuration.

C. You used @Controller instead of @RestController without @ResponseBody.

D. You did not start the Spring Boot application.

Solution

1. Step 1: Understand Springdoc endpoint detection

   Springdoc detects REST endpoints typically annotated with @RestController or @Controller + @ResponseBody.

2. Step 2: Identify missing @ResponseBody effect

   If you use @Controller without @ResponseBody, Springdoc may not detect endpoints as REST APIs, so docs show empty.

3. Final Answer:

   You used @Controller instead of @RestController without @ResponseBody. -> Option C

4. Quick Check:

   Missing @ResponseBody means no REST endpoints detected [OK]

Hint: Use @RestController or @Controller + @ResponseBody for docs [OK]

Common Mistakes:

• Assuming @Controller alone is enough for REST docs
• Forgetting to run the app before checking docs
• Thinking XML config affects Springdoc detection

5. How can API documentation improve teamwork and maintenance in a Spring Boot project?

hard

A. By providing clear, up-to-date info on endpoints, it helps teammates understand and use APIs correctly.

B. By hiding internal API details to prevent misuse.

C. By automatically fixing bugs in the code.

D. By replacing the need for writing unit tests.

Solution

1. Step 1: Identify the role of API docs in teamwork

   Clear API docs explain how endpoints work, so teammates can use and build on them without confusion.

2. Step 2: Understand maintenance benefits

   Up-to-date docs reduce errors and speed up onboarding, making maintenance easier and safer.

3. Final Answer:

   By providing clear, up-to-date info on endpoints, it helps teammates understand and use APIs correctly. -> Option A

4. Quick Check:

   Clear docs improve teamwork and maintenance [OK]

Hint: Good docs = better teamwork + easier maintenance [OK]

Common Mistakes:

• Thinking docs hide API details
• Believing docs fix bugs automatically
• Assuming docs replace testing