一、整合
1、版本
Spring Boot 2.6.x以下版本
比如下面版本组合是兼容的
Spring Boot版本 | Swagger 版本 |
---|---|
2.5.6 | 2.9.2 |
Spring Boot 2.6.x以上
Spring Boot版本 | Swagger 版本 |
---|---|
2.6.5 | 3.0.0 |
2、引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
3、yaml文件添加配置
spring:
application:
name: rbac
mvc:
pathmatch:
matching-strategy: ant_path_matcher
4、开启Swagger
在SpringBoot的启动类 添加@EnableOpenApi
注解,开启Swagger支持
@SpringBootApplication
@EnableOpenApi
public class RbacApplication {
public static void main(String[] args) {
SpringApplication.run(RbacApplication.class, args);
}
}
5、启动服务器,访问swagger-ui,查看接口文档
http://localhost:9000/swagger-ui/
二、Swagger常用配置注解
1、@Api
用于请求的类上,表示对类的说明
-
tags=“说明该类的作用,可以在ui界面上看到的注解”
-
value=“在UI界面上看不到,所以不需要配置”
2、@ApiOperation
用在请求的方法上,说明方法的用途、作用
-
value=“说明方法的用途、作用”
-
notes=“方法的备注说明”
@ApiOperation(value = "说明方法的用途、作用",notes = "方法的备注说明")
@GetMapping("/{id}")
public Result queryByid(@PathVariable Long id) {
3、@ApiImplicitParams
用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
-
name:参数名
-
value:参数的汉字说明、解释
-
required:参数是否必须传
-
paramType:参数放在哪个地方
-
header --> 请求参数的获取:@RequestHeader
-
query --> 请求参数的获取:@RequestParam
-
-
path(用于restful接口)–> 请求参数的获取:@PathVariable
-
dataType:参数类型,默认String,其它值dataType=“Integer”
-
div(不常用)
-
form(不常用)
-
defaultValue:参数的默认值
@GetMapping("all")
@ApiOperation(value = "条件查询",notes ="可以根据用户姓名,注册时间等查询" )
@ApiImplicitParams({
@ApiImplicitParam(name = "realName",value = "用户名",required = false,paramType = "query"),
@ApiImplicitParam(name = "dateRange",value = "注册时间范围",required = false,paramType = "query"),
@ApiImplicitParam(name = "currentPage",value = "当前页",required = true,paramType = "query",dataType = "Integer"),
@ApiImplicitParam(name = "pageSize",value = "每页显示的条数",required = true,paramType = "query",dataType = "Integer"),
})
public Result getAll(@RequestParam(value = "realName", required = false) String realName,
@RequestParam(value = "dateRange", required = false) String[] dateRange,
@RequestParam(value = "currentPage", required = false) Integer currentPage,
@RequestParam(value = "pageSize", required = false) Integer pageSize) {}
4、@ApiResponses:
用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
-
code:数字,例如400
-
message:信息,例如"请求参数没填好"
-
response:抛出异常的类
@ApiOperation(value = "说明方法的用途、作用",notes = "方法的备注说明")
@ApiResponses({
@ApiResponse(code = 401,message = "未认证"),
@ApiResponse(code = 403,message = "无权访问"),
@ApiResponse(code = 404,message = "未找到")
})
@GetMapping("/{id}")
public Result queryByid(@PathVariable Long id) {}
5、@ApiModel
用于响应类上,表示一个返回响应数据的信息
这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候
@ApiModel 用类上,描述类信息
@ApiModelProperty:用在属性上,描述响应类的属
@ApiModel("用户类")
public class SysUser implements Serializable {
@ApiModelProperty("用户id")
private Integer id;
@ApiModelProperty("用户密码")
private String password;
@ApiModelProperty("用户电话")
private String telephone;
@ApiModelProperty("用户名")
private String realname;
@ApiModelProperty("出生年月")
@DateTimeFormat(pattern = "yyyy-MM-dd")
@JsonFormat(pattern = "yyyy-MM-dd")
private Date birthday;
@ApiModelProperty("头像")
private String headimg;
@ApiModelProperty("是否可用")
private Integer available;
private Integer did;
private String begin;
private String end;
private int pageSize;
private int startPage;
private static final long serialVersionUID = 1L;
}
三、API信息配置
自定义配置类Swagger3Config
package com.wn.rbac.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
@Configuration
public class Swagger3Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
.groupName("开发组001")
.select()
.apis(RequestHandlerSelectors.basePackage("com.wn.rbac.controller")) // 指定扫描的包 常用方式
.build()
.apiInfo(createApiInfo());
}
@Bean
public ApiInfo createApiInfo() {
return new ApiInfo(
"Api Documentation", //标题
"XX项目Api文档",//描述
"3.0", //版本
"https://www.kszs.xyz",//团队链接
new Contact("fengSir", "https://www.kszs.xyz", "151303131@qq.com"),
"Apache 2.0",
"https://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
四、Docket开关|过滤|分组 配置详解
1、开关设置 enable
开发环境才会用到swagger;正式环境需要关闭swagger;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
.groupName("开发组001")
.select()
.apis(RequestHandlerSelectors.basePackage("com.wn.rbac.controller")) // 指定扫描的包 常用方式
.build()
.enable(false)
.apiInfo(createApiInfo());
}
2、设置过滤
apis (必选有调用select) 参数:
-
any 所有都有效
-
none都无效
-
withClassAnnotation 根据类注解
-
withMethodAnnotation 根据方法注解
-
basePackage根据包路径(主要)
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
/*其它省略先*/
.select()
.apis(RequestHandlerSelectors.basePackage("org.example.controller"))
.apiInfo(createApiInfo());
}
最后都要加build方法:
RequestHandlerSelectors.withClassAnnotation(Api.class)
RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)
3、设置分组
.groupName("开发组001")