Swagger官网地址:https://swagger.io/
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。功能主要包含以下几点:
- 使得前后端分离开发更加方便,有利于团队协作。
- 接口文档在线自动生成,降低后端开发人员编写接口文档的负担。
- 接口功能测试。
使用Swagger只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等。
Knife4j(小刀 four java,log4j哈哈)
如果直接使用Swagger,需要按照Swagger的规范定义接口,实际上就是编写Json文件,编写起来比较繁琐、并不方便。
而在项目中使用,我们一般会选择一些现成的框架来简化文档的编写,而这些框架是基于Swagger的(例如 knife4j)。
Knife4j是一款基于Swagger的增强工具,官网地址:https://doc.xiaominfo.com/
使用knife4j只需在pom.xml中引入如下依赖即可:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
1. 使用方式
1、导入knife4j起步依赖:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
2、编写Swagger配置类:
package com.baidou.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2配置类(生成接口文档)
*
* @author 白豆五
* @version 2023/1/21
* @since JDK8
*/
@Configuration
@EnableSwagger2 //开启swagger2注解支持
@EnableKnife4j //开启Knife4j注解支持
public class SwaggerConfig {
@Bean
public Docket webApiConfig() { //生成接口文档的清单
// 文档类型
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(webApiInfo())
.select()
//指定controller包扫描路径
.apis(RequestHandlerSelectors.basePackage("com.baidou.controller"))
.paths(PathSelectors.any())
.build();
}
//配置api信息
private ApiInfo webApiInfo() {
return new ApiInfoBuilder()
.title("网站-API文档")
.description("本文档描述了xxx管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("白豆五", "https://blog.csdn.net/qq_46921028", "13212341234@163.com"))
.build();
}
}
注意: Docket声明时,有一个包扫描的路径,该路径指定的是Controller所在包的路径。因为Swagger在生成接口文档时,就是根据这里指定的包路径,自动的扫描该包下的@Controller, @RestController, @RequestMapping等SpringMVC的注解,依据这些注解来生成对应的接口文档。
3、 设置静态资源映射(对Swagger的静态资源放行)
由于Swagger生成的在线文档中,涉及到很多静态资源,这些静态资源需要添加静态资源映射,否则接口文档页面无法访问。
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
// 静态资源放行
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/web/**").addResourceLocations("classpath:/web/");
// 对swaggger静态资源放行
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
如果配置拦截器,需要对以下资源放行:
"/doc.html",
"/webjars/**",
"/swagger-resources",
"/v2/api-docs"
4、访问swagger:http://localhost:8081/doc.html
2. 常用注解
Swagger提供了很多的注解,通过这些注解,我们可以更好更清晰的描述我们的接口,包含接口的请求参数、响应数据、数据模型等。核心的注解,主要包含以下几个:
注解 | 位置 | 说明 |
---|---|---|
@Api | 类 | 添加到Controller类上,表示对类的说明 |
@ApiModel | 类(通常是实体类) | 描述实体类的作用 |
@ApiModelProperty | 属性 | 描述实体类的属性 |
@ApiOperation | 方法 | 说明方法的用途、作用 |
@ApiImplicitParams | 方法 | 表示一组参数说明 |
@ApiImplicitParam | 方法 | 用在@ApiImplicitParams注解中,指定一个请求参数的各个方面的属性 |
@ApiParam | 方法形参上 | 描述接口方法的形参 |
示例:注解的使用
在实体类中使用:
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("学生实体类")
public class Stu implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty("主键")
private Long id;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("年龄")
private Integer age;
@ApiModelProperty("电话")
private String tel;
}
在Controller类中使用:
@RestController
@RequestMapping("/stu")
@Api(tags = "学生相关接口")
public class StuController {
@Autowired
StuMapper stuMapper;
@GetMapping("/list")
@ApiOperation(value = "获取学生列表接口")
public String findList() {
List<Stu> list = stuMapper.selectAll();
return JSON.toJSONString(list);
}
@GetMapping()
@ApiOperation(value = "通过名字获取学生列表接口")
// required = true 表示必须传递参数
public String select( @ApiParam(value = "学生姓名",required = true) @RequestParam String name) {
List<Stu> list = stuMapper.select(name);
return JSON.toJSONString(list);
}
@DeleteMapping("/{id}")
@ApiOperation(value = "通过id删除学生信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "学生的id",required = true),
})
public String delete(@PathVariable Long id) {
int row = stuMapper.deleteStu(id);
return row == 1 ? "ok" : "error";
}
@PostMapping("/save")
@ApiOperation(value = "新增学生信息")
public String save(@ApiParam("学生信息") @RequestBody Stu stu) {
int row = stuMapper.save(stu);
return row == 1 ? "ok" : "error";
}
@PutMapping("/update")
@ApiOperation(value = "修改学生信息")
public String update(@ApiParam("学生信息")@RequestBody Stu stu) {
int row = stuMapper.update(stu);
return row == 1 ? "ok" : "error";
}
}
只需使用Swagger提供的注解便可生成接口文档。