SpringBoot 3.2.5 引入Swagger(OpenApi)

news2025/10/31 17:26:05

SpringBoot 3.2.5 引入Swagger（OpenApi）

pom文件
配置文件
启动类
Controller 层
ApiFox
- - - 题外话

springdoc-openapi 和 swagger 都可以用，用其中一个就行，不用两个都引入。

这里简单记录以下springdoc-openapi。

springdoc-openapi(Java库)有助于使用 SpringBoot 项目自动生成 API 文档。

pom文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
    
 	<!-- 当前项目id -->
    <groupId>openApi</groupId>
    <artifactId>openApi</artifactId>
    <version>3.2.5</version>

    <name>openApi</name>
    <description>这里写你自己的项目描述</description>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- SpringBoot 提供的 web 依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>3.2.5</version>
        </dependency>

        <!-- lombok 依赖 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
        </dependency>

        <!-- validation 参数校验依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
            <version>3.2.5</version>
        </dependency>
        <dependency>
            <groupId>jakarta.validation</groupId>
            <artifactId>jakarta.validation-api</artifactId>
            <version>3.0.2</version>
        </dependency>

        <!-- swagger-ui依赖 https://springdoc.org/ -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
    </dependencies>
</project>

配置文件

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
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 {
	//个人认为，以下括号里的内容，都可乱写，写啥都行，只要是字符串就行
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("OpenApi的Swagger")
                        .description("springdoc-openapi-starter-webmvc-ui")
                        .version("springdoc-openapi v2.5.0")
                        .license(new License()
                                .name("SprigBoot3.2.5")
                                //url，这里写的是SpringBoot的地址
                                .url("https://spring.io/projects/spring-boot"))
                ).externalDocs(new ExternalDocumentation()
                        .description("springdoc-openapi v2.5.0")
                        //url,写的是springdoc-openapi的地址
                        .url("https://springdoc.org/#google_vignette"));
    }
}

启动类

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@Slf4j
@SpringBootApplication
public class BigEventApplication implements CommandLineRunner {
    public static void main(String[] args) {
        SpringApplication.run(BigEventApplication.class, args);
    }

    @Override
    public void run(String... args) {
    	//端口号默认8080
        log.info("Tomcat在端口 " + 8080 + " (http)上启动：\n");
        
        String hostname = "localhost";
        String http = "http://";
        
        log.info("Api文档 浏览器访问地址如下：");
        log.info(http + hostname + ":" + 8080 + "/swagger-ui/index.html\n");
        
        log.info("ApiFox的 URL方式 导入路径为：");
        log.info(http + hostname + ":" + 8080 + "/v3/api-docs\n");
    }
}

Controller 层

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Validated
@RestController
@RequiredArgsConstructor
@Tag(name = "Xxx名字", description = "这里可以多写几个字，用来描述xxx，描述的详细一点")
@RequestMapping("/路径")
public class XxxController {

    private final XxxService service;
    
    @Operation(summary = "删除", description = "根据 id 删除")
    @DeleteMapping("/delete/{id}")
    public Result<String> clean(@NotBlank(message = "id 不可为空") @PathVariable String id) {
        boolean b = service.removeById(id);
        return b ? Result.success("删除成功") : Result.error("删除失败");
    }
}