SpringBoot3 整合 Swagger3

最新推荐文章于 2024-07-21 22:41:49 发布

juiwi

最新推荐文章于 2024-07-21 22:41:49 发布

阅读量349

点赞数 7

文章标签： java spring boot

本文链接：https://blog.csdn.net/qq_65587446/article/details/137015623

版权

pom.xml 的配置文件

引入相应依赖

<?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 https://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.1.8</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <groupId>com.example</groupId>
  <artifactId>demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>demo</name>
  <description>demo</description>
  <properties>
    <java.version>17</java.version>
  </properties>
  <dependencies>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <!-- openAPI包，替换 Swagger 的 SpringFox -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.2.0</version>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>

  </dependencies>
</project>

yml配置文件

server:
  port: 8080
  servlet:
    context-path: /Juiwi # 应用访问路径

Java配置类文件

新增OpenAPIConfig.java配置类，配置 Swagger3 基本内容。


import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("测试 title")
                        .description("SpringBoot3 集成 Swagger3")
                        .version("v1"))
                .externalDocs(new ExternalDocumentation()
                        .description("项目API文档")
                        .url("/"));
    }
}

访问地址区别

swagger2 的访问地址：http://localhost:8080/Juiwi/swagger-ui.html

swagger3 的访问地址：http://localhost:8080/Juiwi/swagger-ui/index.html

swagger3 常用注解

默认是可以不配置任何注解的，不过增加一些注解可以使swagger可读性更加好。

注解SpringBoot3 版本	替换旧注解 SpringBoot2 版本	描述
@Tag	@Api	用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。
@Operation	@ApiOperation	用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
@Parameter	@ApiParam	@Parameter作用于请求方法上，定义api参数的注解。
@Parameters、 @Parameter	@ApiImplicitParams、@ApiImplicitParam	都可以定义参数（1）@Parameters：用在请求的方法上，包含一组参数说明（2）@Parameter：对单个参数的说明
io.swagger.v3.oas.annotations新包中的@ApiResponses、@ApiResponse	旧包io.swagger.annotations中的@ApiResponses、@ApiResponse	进行方法返回对象的说明。
@Schema	@ApiModel、@ApiModelProperty	@Schema用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景）。