Quickly Add Swagger UI to Spring Boot 3.5.6 Using springdoc 2.7.0

Overview

Swagger UI can be generated automatically for Spring Boot applications using springdoc-openapi. The following steps describe how to integrate Swagger with Spring Boot 3.5.6.

Prerequisites

Versions

JDK 21

Spring Boot 3.5.6

springdoc-openapi 2.7.0

Maven configuration

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.6</version>
</parent>

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.7.0</version>
    </dependency>
</dependencies>

Spring Boot 3.5.6 requires springdoc-openapi 2.7.0. For earlier Spring Boot 3.2+ versions, use 2.6.0.

OpenAPI configuration

Create a configuration class that supplies an OpenAPI bean with basic metadata.

package com.nodcat.config;

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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {
    /** Configure API documentation metadata */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Qingdao Forest Fire Management Platform API")
                .description("APIs for fire monitoring, emergency command, user management, etc.")
                .version("v1.0.0")
                .contact(new Contact()
                    .name("Technical Support")
                    .email("[email protected]")
                    .url("http://fireplatform.com"))
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0")));
    }
}

Controller annotations

Annotate controller methods with @Operation, @Parameter and @Schema to describe operations, request parameters and response models.

@GetMapping("/list")
@Operation(summary = "Get merchant package list")
public Result list(@Parameter(description = "Page number", required = true)
                  @RequestParam(value = "page", required = true) Integer page) {
    return Result.success("Package list");
}

Key annotations: @Operation – sets the operation summary. @Parameter – describes request parameters. @Schema – adds documentation to response models.

Standard response wrapper

A unified Result class simplifies front‑end handling and is annotated with @Schema for documentation.

package com.nodcat.common.json;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;

@Data
@Schema(description = "Response result class")
public class Result implements Serializable {
    @Schema(description = "Result flag", example = "true")
    private Boolean flag;
    @Schema(description = "Result code")
    private Integer code;
    @Schema(description = "Message")
    private String msg;
    @Schema(description = "Data payload")
    private Object data;

    public Result(Boolean flag, Integer code, String msg, Object data) {
        this.flag = flag;
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public static Result success(Object data) {
        return new Result(true, 200, "Response successful", data);
    }
    public static Result success(Object data, String msg) {
        return new Result(true, 200, msg, data);
    }
    public static Result success() {
        return new Result(true, 200, "Response successful", null);
    }
    public static Result error(String msg) {
        return new Result(false, 500, msg, null);
    }
    public static Result errorMsg(Integer code, String msg) {
        return new Result(false, code, msg, null);
    }
}

Running the application

After the Spring Boot application starts, Swagger UI is accessible at:

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

Compatibility note

Using springdoc-openapi 2.6.0 with Spring Boot 3.5.6 results in a NoClassDefFoundError for org.springframework.web.method.ControllerAdviceBean. Upgrade to version 2.7.0 to avoid the error.

Illustrations