1. 环境
- spring boot版本：2.7.4
- spring swagger版本：3.0.0
- java版本：8
2. 具体操作
2.1 引入spring swagger的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
这是spring swagger 3.0版本的依赖，里面整合了spring-swagger2和spring-swagger-ui的依赖。如果要使用低于3.0版本的，可以单独引入这两个依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>版本号</version>
</dependency>
<!--这个依赖主要是看swagger-ui界面的依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>版本号</version>
</dependency>
2.2 配置swagger
package com.mcj.music.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @author mcj
* @date 2022/10/15 13:18
* @email [email protected]
* @description swagger配置类
*/
@Configuration
@EnableOpenApi // 开启swagger功能 swagger3.0.0版本以前使用@EnableSwagger2开启 注意：这个注解是springfox-boot-starter依赖中的注解，如果不存在的话请引入这个依赖
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 配置文档的信息
.enable(true) // 是否开启，true开启，false隐藏，生产环境最好隐藏
.select() // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.mcj.music.controller")) // 扫描的路径包,也就是会生成接口文档的包路径，设置basePackage会将包下的所有被@Api标记类的所有方法作为api
.paths(PathSelectors.any()) // 指定路径处理，也就是会生成接口文档的路径，PathSelectors.any()代表所有的路径
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("音乐网站") // 设置文档标题
.description("接口描述") // 文档描述
.termsOfServiceUrl("http://localhost:8888") // 服务条款URL
.version("V0.0.0") // 版本号
.build();
}
}
2.3 swagger常用注解的使用
@Api注解的使用
@Api注解用于标注一个Controller,一般在默认情况下Swagger-core只会扫描解析标有@Api注解的类，从而忽略其他资源的类
@Api注解常用的一些属性
| 属性 | 描述 |
|---|---|
| value | 描述类的作用 |
| tags | 说明该类的作用，非空时将覆盖value的值 |
| hidden | 默认为false， 配置为true 将在文档中隐藏，这个也不常用 |
@ApiOperation注解的使用
@ApiOperation主要是用在请求的方法上，说明方法的用途、作用
@ApiOperation常用的一些属性
| 属性 | 描述 |
|---|---|
| value | 说明方法的用途、作用 |
| notes | 方法的备注 |
| tags | 操作标签，非空时将覆盖value的值 |
| httpMethod | 指定HTTP方法，"GET","HEAD","POST","PUT","DELETE" |
| response | 返回对象 |
@ApiModel注解的使用
@ApiModel主要用在字段的实体类上，对实体类进行个描述
@ApiModelProperty
@ApiModelProperty主要用在实体类中的字段上，对其属性进行描述
@ApiModelProperty常用的一些属性
| 属性 | 描述 |
|---|---|
| value | 该字段的简要说明。 |
| name | 允许覆盖属性名称 |
| dataType | 参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。 |
| required | 参数是否必传，默认为false |
| example | 对该字段举个例子 |
@ApiImplicitParams与@ApiImplicitParam
它们两个都是作用在方法上用来设置参数，不过不同的是@ApiImplicitParams可以包含多个@ApiImplicitParam用来设置多个参数，而@ApiImplicitParam仅仅只是用来设置一个参数。
@ApiImplicitParam注解的一些常用属性
| 属性 | 描述 |
|---|---|
| name | 参数名 |
| value | 参数的具体意义，作用 |
| required | 参数是否必填 |
| dataType | 参数的数据类型 |
| paramType | 查询参数类型 |
2.4 访问swagger接口文档
接口文档的地址为http://localhost:8888/swagger-ui/index.html，前面的地址是你项目的地址，这个是swagger 3.0.0版本的访问地址，如果是低版本的访问地址则是http://localhost:8888/swagger-ui.html
3. 问题
3.1 问题：项目启动时控制台报错
原因：这是因为Springboot2.6以后将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错
解决：
- 在配置文件application.properties中添加下面的语句将其路径改回即可
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
- 将spring boot版本降低到2.6版本以下
3.2 问题：打开spring swagger-ui页面报错
原因：这边是我使用@ApiImplicitParams与@ApiImplicitParam注解时参数的名称写的有问题
解决：修改@ApiImplicitParam注解里面的name名成就行了
4. 小结
4.1 开启swagger的注解3.0版本与以前的版本是不一样的，需要注意一下，3.0版本是使用@EnableOpenApi，而之前的版本则是使用@EnableSwagger2注解
4.2 由于swagger 3.0版本把swagger-ui的前端html页面位置换了，所以在访问的时候记得要换访问路径