Article 12: API Documentation with Swagger / OpenAPI

1. Introduction

Good APIs are not enough. Well-documented APIs are what teams can actually use.

Swagger / OpenAPI helps you:

• See all APIs in one place
• Try APIs from the browser
• Share clear contracts with frontend & clients

Spring Boot makes API documentation almost automatic.

---

2. What Is OpenAPI?

OpenAPI is a standard specification for describing REST APIs.

Swagger is a tooling ecosystem built around OpenAPI that provides:

• Swagger UI
• API testing interface
• Interactive documentation

---

3. Why Swagger Is Important

Without Swagger:

• Developers read code to understand APIs
• High dependency on backend team
• Miscommunication between teams

With Swagger:

• APIs are self-explanatory
• Frontend can work independently
• Faster onboarding

---

4. Adding Swagger (Springdoc OpenAPI)

Spring Boot 3 uses springdoc-openapi.

Add to pom.xml:

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

(No configuration required)

---

5. Accessing Swagger UI

Start your application and open:

http://localhost:8080/swagger-ui.html

or

http://localhost:8080/swagger-ui/index.html

You’ll see:

• All controllers
• All endpoints
• Request/response schemas

---

6. Understanding Swagger UI

Swagger UI shows:

• HTTP methods (GET, POST, etc.)
• Endpoint paths
• Request body structure
• Response status codes

You can:

• Try APIs directly
• Send real requests
• See responses instantly

---

7. Improving API Documentation with Annotations

7.1 Documenting Controller

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

---

7.2 Documenting Endpoints

@Operation(summary = "Create a new user")
@PostMapping
public User createUser(@RequestBody UserRequest request) {
    return userService.createUser(request);
}

---

7.3 Documenting Fields

public class UserRequest {

    @Schema(description = "User name", example = "Bharat")
    private String name;

    @Schema(description = "User email", example = "bharat@email.com")
    private String email;
}

---

8. Hiding Internal APIs

@Hidden
@GetMapping("/internal")
public String internalApi() {
    return "Hidden";
}

Useful for:

• Admin APIs
• Internal endpoints

---

9. Grouping APIs

@Tag(name = "Admin APIs")
@RestController
@RequestMapping("/admin")
public class AdminController {
}

Keeps large projects organized.

---

10. Common Swagger Issues

❌ Swagger not loading → dependency mismatch
❌ APIs missing → controller not scanned
❌ Security blocking Swagger

✔ Swagger works best before enabling strict security

---

11. Best Practices

✔ Always include Swagger in dev/test
✔ Disable or secure Swagger in prod
✔ Keep summaries short and clear
✔ Use examples generously

---

12. What You Should Understand Before Moving On

You should now know:

• What OpenAPI is
• How Swagger UI works
• How to document APIs
• Why documentation matters

---

13. What’s Next?

➡ Article 13: Spring Security Basics

• Authentication vs Authorization
• Security filter chain
• Securing APIs

Type Next when you’re ready.