How to use Swagger with Spring Boot

  Your controllers and models
  (@RestController, @GetMapping, records, validation annotations)
                 |
                 v   springdoc scans them at startup
  OpenAPI specification  ->  http://localhost:8080/v3/api-docs  (JSON)
                 |
                 v   rendered by
  Swagger UI             ->  http://localhost:8080/swagger-ui/index.html

<properties>
    <!-- use the latest springdoc release for your Spring Boot version -->
    <springdoc.version>2.8.9</springdoc.version>
</properties>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc.version}</version>
</dependency>

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9'
}

package com.example.users;

public record UserRequest(String name, String email) {
}

package com.example.users;

public record UserResponse(long id, String name, String email) {
}

package com.example.users;

import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

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

    private final Map<Long, UserResponse> users = new ConcurrentHashMap<>();
    private final AtomicLong ids = new AtomicLong();

    @GetMapping
    public List<UserResponse> getAllUsers() {
        return List.copyOf(users.values());
    }

    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable long id) {
        UserResponse user = users.get(id);
        return user != null ? ResponseEntity.ok(user) : ResponseEntity.notFound().build();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserResponse createUser(@RequestBody UserRequest request) {
        long id = ids.incrementAndGet();
        UserResponse user = new UserResponse(id, request.name(), request.email());
        users.put(id, user);
        return user;
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable long id) {
        users.remove(id);
    }
}

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "Create, read and delete users")
public class UserController {

    @Operation(summary = "Get user by ID", description = "Returns one user using the user ID")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "User found"),
            @ApiResponse(responseCode = "404", description = "User not found")
    })
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(
            @Parameter(description = "ID of the user", example = "101")
            @PathVariable long id) {
        UserResponse user = users.get(id);
        return user != null ? ResponseEntity.ok(user) : ResponseEntity.notFound().build();
    }
}

package com.example.users;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

@Schema(description = "Data needed to create a user")
public record UserRequest(

        @Schema(description = "Full name of the user", example = "Asha Verma")
        @NotBlank
        @Size(max = 100)
        String name,

        @Schema(description = "Email address", example = "asha@example.com")
        @NotBlank
        @Email
        String email) {
}

package com.example.users;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "A user stored in the system")
public record UserResponse(

        @Schema(description = "Unique user ID", example = "101", accessMode = Schema.AccessMode.READ_ONLY)
        long id,

        @Schema(description = "Full name of the user", example = "Asha Verma")
        String name,

        @Schema(description = "Email address", example = "asha@example.com")
        String email) {
}

package com.example.config;

import java.util.List;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI userManagementOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("User Management API")
                        .version("1.0")
                        .description("API documentation for the User Management System")
                        .contact(new Contact().name("API Team").email("api-team@example.com"))
                        .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0")))
                .servers(List.of(
                        new Server().url("http://localhost:8080").description("Local"),
                        new Server().url("https://api.example.com").description("Production")));
    }
}

springdoc:
  api-docs:
    path: /v3/api-docs            # where the JSON specification is served
  swagger-ui:
    path: /swagger-ui.html        # short address for Swagger UI
    operations-sorter: method     # sort endpoints by HTTP method
    tags-sorter: alpha            # sort tags alphabetically
    try-it-out-enabled: true      # open "Try it out" by default
  packages-to-scan: com.example   # only document controllers in this package
  paths-to-match: /api/**         # only document these paths

package com.example.config;

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ApiGroupsConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/api/users/**", "/api/products/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/api/admin/**")
                .build();
    }
}

package com.example.config;

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT")
public class OpenApiSecurityConfig {
}

import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@RestController
@RequestMapping("/api/users")
@SecurityRequirement(name = "bearerAuth")      // all endpoints here need a token
public class UserController {
    // ...
}

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.http.ProblemDetail;

@Operation(summary = "Create a user")
@ApiResponses({
        @ApiResponse(responseCode = "201", description = "User created"),
        @ApiResponse(responseCode = "400", description = "Invalid input",
                content = @Content(mediaType = "application/problem+json",
                        schema = @Schema(implementation = ProblemDetail.class)))
})
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public UserResponse createUser(@Valid @RequestBody UserRequest request) {
    long id = ids.incrementAndGet();
    UserResponse user = new UserResponse(id, request.name(), request.email());
    users.put(id, user);
    return user;
}

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                    // only administrators may open the API documentation
                    .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").hasRole("ADMIN")
                    .requestMatchers("/api/**").authenticated()
                    .anyRequest().denyAll())
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

# Download the specification while the application is running
curl -s http://localhost:8080/v3/api-docs.yaml -o openapi.yaml