SpringBoot 3.2.5 引入Swagger(OpenApi)

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 {//个人认为，以下括号里的内容，都可乱写，写啥都行，只要是字符串就行@Beanpublic 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);}@Overridepublic void run(String... args) {//端口号默认8080log.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("删除失败");}
}