文章目录
- 一、Swagger是什么？
- 二、使用步骤
- 1.引入swagger3依赖
- 2.添加swagger.conf配置类
- 3.添加application.yml配置
- 4.查看是否整合成功
- 5.常用注解
- 6.swagger美化
- 总结
一、Swagger是什么？
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
二、使用步骤
1.引入swagger3依赖
代码如下：
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>
2.添加swagger.conf配置类
代码如下：
package com.uhu.swagger;import io.swagger.models.auth.In;
import liquibase.repackaged.org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import org.springframework.context.annotation.Configuration;/*** @author liujunjie* @description swagger配置* @create 2023-11-06 15:16**/
@Configuration
// 声明开启swagger2
@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {/*** 是否开启swagger*/@Value("${uhu.swagger.enable}")private Boolean enable;/*** 标题*/@Value("${uhu.swagger.title}")private String title;/*** 版本*/@Value("${uhu.swagger.version}")private String version;/*** 描述*/@Value("${uhu.swagger.description}")private String description;/*** 扫描的包*/@Value("${uhu.swagger.scanPackage}")private String scanPackage;/*** 接口调试地址*/@Value("${uhu.swagger.host}")private String host;@BeanDocket api() {// springfox 的基本API配置return new Docket(DocumentationType.OAS_30)// 将映射的路径当作base Path，添加给apis.pathMapping("/")// 定义是否开启swagger，false为关闭，可以通过变量控制.enable(enable)// 将api的元信息设置为包含在json ResourceListing响应中。.apiInfo(apiInfo())// 接口调试地址.host(host)// 选择哪些接口作为swagger的doc发布.select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build()// 支持的通讯协议集合.protocols(new HashSet<>(Arrays.asList("http", "https")))// 授权信息设置，必要的header token等认证信息.securitySchemes(Collections.singletonList(new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue())))// 授权信息全局应用.securityContexts(Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build()));}/*** API 页面上半部分展示信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(title + " Api Doc").description(description).contact(new Contact("xxx", null, "xxx@mail.com")).version(version).build();}/*** 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息*/@SuppressWarnings("unchecked")@Overridepublic void addInterceptors(InterceptorRegistry registry) {try {Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);if (registrations != null) {for (InterceptorRegistration interceptorRegistration : registrations) {interceptorRegistration.excludePathPatterns("/swagger**/**").excludePathPatterns("/webjars/**").excludePathPatterns("/v3/**").excludePathPatterns("/doc.html");}}} catch (Exception e) {e.printStackTrace();}}}3.添加application.yml配置
代码如下：
uhu:swagger:enable: truetitle: ${spring.application.name}version: 1.0.0description: 企业合规管理系统接口文档scanPackage: com.uhuhost: http://localhost:${server.port}
4.查看是否整合成功
项目启动，访问 http://localhost:port/context-path/swagger-ui.html
5.常用注解
| 注解 | 注解说明 | 用法 |
|---|---|---|
| @Api | 类注解，用于给控制器取别名 |  |
| @ApiOperation | 常用来描述方法 |  |
| @ApiModel和@ApiModelProperty | 描述请求响应描述 |  |
| @ApiParam | 路径参数注解 |  |
| @ApiImplicitParam和@ApiImplicitParams | 描述方法参数 |  |
6.swagger美化
添加美化依赖
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version>
</dependency>
添加yml配置
knife4j:enable: truebasic:enable: trueusername: adminpassword: adminsetting:language: zh-CN
重启服务
访问 http://localhost:port/context-path/doc.html
总结
通过集成 Swagger3，我们可以方便地生成接口文档，使得前后端开发协同更加高效，通过knife4j进行美化后的页面更加适合国人的阅读习惯。
以上就是SpringBoot整合Swagger3的方式，是不是很简单，赶紧用起来吧！！！
