Springboot3整合OpenAPI(Swagger3)

## Springboot3整合OpenAPI(Swagger3)

Swagger是一个用于设计、构建、记录和使用RESTful web服务的开源软件框架。Swagger 3（OpenAPI 3.0）提供了更加强大和灵活的API文档生成能力。本教程将指导您如何在Spring Boot 3项目中集成Swagger3，并使用Knife4j作为UI界面。

### 1. 添加依赖

首先，您需要在项目的`pom.xml`文件中添加Swagger3的依赖。

~~~xml
<!--springdoc-openapi-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.1.0</version>
</dependency>
~~~



### 2. 配置Swagger

在Spring Boot项目中创建一个配置类`SwaggerConfig`，并添加Swagger的配置信息。

~~~java
package cn.hxzy.config;


import io.swagger.v3.oas.models.ExternalDocumentation;
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;


import java.util.ArrayList;

@Configuration
public class SwaggerConfig {

    //访问路径：
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("标题")
                        .contact(new Contact())
                        .description("我的API文档")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }

}

~~~



### 3. 实体类和控制层注解

在您的实体类和控制层中使用Swagger注解来描述API。

**实体类**

~~~java
// 实体类注解示例
import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.ColumnWidth;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.util.Date;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@Schema(name = "Employee", description = "员工实体类")
public class Emp {
    
    @Schema(description = "ID")
    private int id;
    
    
    @Schema(description = "用户名")
    private String names;
    
   
    @Schema(description = "工资")
    private double salary;
    
   
    @Schema(description = "生日")
    private Date birthday;
    
    @ColumnWidth(20)
    @Schema(description = "头像")
    private String photo;

}

~~~



**控制器**

~~~java
package cn.hxzy.controller;

import cn.hxzy.pojo.Result;
import cn.hxzy.pojo.User;
import cn.hxzy.service.UserService;
import cn.hxzy.utils.JwtUtil;
import cn.hxzy.utils.Md5Util;
import cn.hxzy.utils.ThreadLocalUtil;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.constraints.Pattern;
import org.hibernate.validator.constraints.URL;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.ValueOperations;
import org.springframework.util.StringUtils;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.TimeUnit;

@RestController
@RequestMapping("/user")
@Tag(name = "用户控制器", description = "用户控制器Controller")
public class UserController {

    @Autowired
    private UserService userService;

    @Operation(summary = "用户注册API", description = "用户注册")
    @PostMapping("/register")
    public Result register(String username,  String password) {
        return null;
    }
   
}

~~~

### 4. 注解说明

Swagger3的注解与Swagger2有所不同，以下是一些常用注解的对照表：

<table><thead><tr><th>Swagger2注解</th><th>Swagger3注解</th><th>注解位置</th></tr></thead><tbody><tr><td>@Api</td><td>@Tag(name = “接口类描述”)</td><td>Controller类上</td></tr><tr><td>@ApiOperation</td><td>@Operation(summary = “接口方法描述”)</td><td>Controller方法上</td></tr><tr><td>@ApiImplicitParams</td><td>@Parameters</td><td>Controller方法上</td></tr><tr><td>@ApiImplicitParam</td><td>@Parameter(description = “参数描述”)</td><td>Controller方法上</td></tr><tr><td>@ApiParam</td><td>@Parameter(description = “参数描述”)</td><td>方法参数上</td></tr><tr><td>@ApiIgnore</td><td>@Parameter(hidden = true) 或 @Operation(hidden = true)</td><td>-</td></tr><tr><td>@ApiModel</td><td>@Schema</td><td>DTO类上</td></tr><tr><td>@ApiModelProperty</td><td>@Schema</td><td>DTO属性上</td></tr></tbody></table>



### 5.拦截器配置

在拦截器的配置中把swagger的所有请求路径加到拦截器的排除列表



```java
package cn.hxzy.config;

import cn.hxzy.interceptors.LoginInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private LoginInterceptor loginInterceptor;


    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //登录接口和注册接口不拦截
        registry.addInterceptor(loginInterceptor)
                .excludePathPatterns("/user/login",
                                     "/user/register","/swagger-resources/**", "/webjars/**", "/v3/**", "/swagger-ui/**");
                 // 排除登录与注册以及Swagger的接口

    }
}
```


### 6. 访问Swagger UI

启动您的Spring Boot应用后，您可以通过以下地址访问Swagger UI：

~~~
http://localhost:8080/doc.html
http://localhost:8080/swagger-ui/index.html
~~~

在这里，您可以查看API文档，测试API接口，并获取相关信息。