Swagger
前言:
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
目前的项目基本都是前后端分离,后端为前端提供接口的同时,还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新,这个时候有可能会忘记更新接口的说明文档,造成一些不必要的问题。
一、Why
作用:
根据在代码中使用自定义的注解来生成接口文档,这个在前后端分离的项目中很重要。这样做的好处是 在开发接口时可以通过swagger 将接口文档定义好,同时也方便以后的维护。
在没有swagger之前,我们可以使用word,excel等功能来书写接口定义文档,但又有一个弊端,即: 在接口发送改变时需要及时的同步接口文档,否则实际的接口与接口文档不相符,则接口文件就失去了作用,甚至会起到反作用。
优点:
- 号称时最流行的 API 框架
- 接口文档在线生成,避免同步的麻烦
- 可以支持在线对接口执行测试
- 支持多语言
二、How
- 导入 knife4j的maven坐标
注意:不可以加provided会限制使用的范围无法被继承
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
- 导入knife4j相关配置 在后端项目的config包下创建Knife4jConfig类:
package com.atguigu.srb.core.config;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import javax.annotation.Resource;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
//【重要】指定Controller包路径
private String basePackage = "com.atguigu.srb.core";
//分组名称
private String groupName = "makabaka";
//主机名
private String host = "Url";
//标题
private String title = "后台管理系统-API文档";
//简介
private String description = "本文档描述了后台管理系统微服务接口定义";
//服务条款URL
private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
//联系人
private String contactName = "Mr.Ke";
// 联系网址
private String contactUrl = "...";
// 联系邮箱
private String contactEmail = "kews1688@163.com";
//版本号
private String version = "1.0.0";
@Resource
private OpenApiExtensionResolver openApiExtensionResolver;
@Bean
public Docket docket() {
// 获取token
List<Parameter> pars = new ArrayList<>();
ParameterBuilder tokenPar = new ParameterBuilder();
tokenPar.name("token")
.description("用户token")
.defaultValue("")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build();
pars.add(tokenPar.build());
//添加head参数end
String groupName = "1.0.0";
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.host(host)
.apiInfo(apiInfo())
.groupName(groupName)
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.regex("/*/admin/.*"))//需要注意的是路劲
.build()
.globalOperationParameters(pars)
.extensions(openApiExtensionResolver.buildExtensions(groupName));
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.contact(new Contact(contactName, contactUrl, contactEmail))
.version(version)
.build();
}
}
注意:必须修改以上配置中的包名,保证是当前项目中控制器类所在的包!其它各项均可不修改,以上配置代码可以从Knife4j的官网找到!
- 最后,还需要在配置文件.yml或者.properties中开启Knife4j的增强模式:
# Knife4j配置
knife4j:
# 是否开启增强模式
enable: true
- 完成后,启动项目,在浏览器中访问http://localhost:8080/doc.html 即可查看当前项目的API文档。
附:
在控制器类上添加@Api注解,并配置tags属性,可以指定模块名称,例如:
@Api(tags = "管理员管理模块") // 新增
@RestController
@RequestMapping(value = "/admins", produces = "application/json; charset=utf-8")
public class AdminController {
// ===== 原有代码 =====
}
在处理请求的方法上添加@ApiOperation注解可以配置业务名称,例如:
@ApiOperation("管理员登录") // 新增
@PostMapping("/login")
public JsonResult<AdminSimpleVO> login(@Validated AdminLoginDTO adminLoginDTO) {
AdminSimpleVO adminSimpleVO = adminService.login(adminLoginDTO);
return JsonResult.ok(adminSimpleVO);
}
当需要指定各业务在API文档中的显示顺序时,可以在处理请求的方法上添加@ApiOperationSupport注解,配置此注解的order属性,最终在显示API文档时,会根据order属性值升序排列,例如
@ApiOperation("管理员登录")
@ApiOperationSupport(order = 900) // 新增
@PostMapping("/login")
public JsonResult<AdminSimpleVO> login(@Validated AdminLoginDTO adminLoginDTO) {
AdminSimpleVO adminSimpleVO = adminService.login(adminLoginDTO);
return JsonResult.ok(adminSimpleVO);
}
通常,建议以上配置的order值至少是2位的数字,并且有预留位置,例如10-19之间的都是增加数据的业务,20-29之间的都是删除数据的业务,30-39之间都是修改数据的业务,40~49之间都是查询数据的业务。
如果控制器处理请求的方法的参数是自定义的封装类型,可以在封装类型的属性上添加@ApiModelProperty来配置参数在文档中的显示,例如:
package package cn.pojo.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotNull;
import java.io.Serializable;
@Data
public class AdminLoginDTO implements Serializable {
@ApiModelProperty(value = "用户名") // 配置参数名
private String username;
@ApiModelProperty("密码") // 配置参数名
private String password;
}
以上@ApiModelProperty除了可以配置参数在API文档中显示的名称以外,还可以配置是否必须,例如:@ApiModelProperty(value = “用户名”, required = true)
另外,还可以配置参数类型等,但是,并不是必须配置,通常框架可以正常自动识别。对于部分名称可能比较特殊(一般人直接看不懂)的属性,或者对值的规范性要求比较明确(例如某些取值为0或1)的属性,可以列举示例,使得查看API文档的人可以参考,例如:@ApiModelProperty(value = “用户名”, required = true, example = “admin”)
除以配置请求参数以外,此属性还可以用于响应结果的类型,例如:
public class JsonResult<T> implements Serializable {
@ApiModelProperty("业务状态码")
private Integer state;
@ApiModelProperty("消息")
private String message;
@ApiModelProperty("数据")
private T data;
// ......
如果以上private T data;的实际值也需要添加说明,则在对应的类的属性上继续使用@ApiModelProperty配置即可!需要注意:此处data属性可以是任意数据类型,必须声明为泛型,不可以是Object,否则将无法应用@ApiModelProperty的配置。
另外,当添加在响应的类型的属性上时,还可以在@ApiModelProperty注解中配置position属性,用于设置各属性在响应的JSON中的显示顺序,例如:@ApiModelProperty(value = “业务状态码”, position = 5)
三、What
总结:
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger行生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等。
主要进行一个get,post,put,delete提交请求的进行一个测试,简单来说就是CRUD操作
官网: https://swagger.io/
每日金句:
看天地,见众生,做自己
参考链接:https://blog.csdn.net/qq_45462360/article/details/125506746