Spring Boot Swagger Documentation (OpenAPI)

1. Introduction

Swagger / OpenAPI is used to automatically generate interactive API documentation for Spring Boot REST APIs.

• Visualize REST endpoints
• Test APIs directly from the browser
• View request/response structures
• Understand API contracts easily

Modern Spring Boot applications use SpringDoc OpenAPI.

2. Swagger UI

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

3. Architecture Overview

Spring Boot Application
        │
        ▼
SpringDoc OpenAPI Library
        │
        ▼
Generates OpenAPI Specification (JSON)
        │
        ▼
Swagger UI
        │
        ▼
Interactive API Documentation

4. Maven Dependency

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

5. Basic REST Controller

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public List<String> getUsers() {
        return List.of("John", "David", "Alice");
    }

    @PostMapping
    public String createUser(@RequestBody String name) {
        return "User created: " + name;
    }
}

6. API Metadata Configuration

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("User Management API")
                        .version("1.0")
                        .description("Spring Boot REST API documentation using Swagger"));
    }
}

7. Swagger Annotations

8. Documented Controller

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

    @Operation(summary = "Get all users")
    @GetMapping
    public List<String> getUsers() {
        return List.of("John", "David", "Alice");
    }

    @Operation(summary = "Create a new user")
    @PostMapping
    public String createUser(@RequestBody String name) {
        return "User created: " + name;
    }
}

9. Model Example

@Schema(description = "User entity")
public class User {

    @Schema(description = "Unique ID of the user")
    private Long id;

    @Schema(description = "Name of the user")
    private String name;

    @Schema(description = "Email address")
    private String email;
}

10. API Responses

@Operation(summary = "Get user by ID")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "User found"),
        @ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
    return new User(id, "John", "john@email.com");
}

11. Swagger URLs

12. Advantages

• Auto documentation
• Interactive API testing
• Standardized OpenAPI specification
• Easy Spring Boot integration

13. Summary

Swagger with Spring Boot enables automatic API documentation and interactive testing using SpringDoc OpenAPI.