前言
前后端分离时代,接口的维护工作显得十分重要。今天我们介绍的Swagger2提供了强大的接口维护能力。
工程介绍
[1] 在pom.xml中导入两个swagger2的模块和一个web模块
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
[2] 编写一个Swagger2的配置类
package com.gs.servicebase;
import com.google.common.base.Predicates;
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.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;
@Configuration
@EnableSwagger2 //swagger注解
public class SwaggerConfig {
@Bean
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(webApiInfo())
.select()
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("网站-课程中心API文档")
.description("本文档描述了课程中心微服务接口定义")
.version("1.0")
.contact(new Contact("Helen", "http://baidu.com", "xxxxx@qq.com"))
.build();
}
}
这里提供的配置类通过@EnableSwagger2启用Swagger2,其中webApiInfo表示这个接口文档的相关描述,paths表明要指定的路径。
此时我们可以启动项目进行测试:
http://localhost:8081/swagger-ui.html (端口号为自己boot项目的端口号)
下面的相关介绍借鉴自博客:https://blog.csdn.net/u012702547/article/details/88775298
[3] 编写相关的接口 (这里只是列举其中的两个, 其中R是我自定义的返回值类型)
@RestController
@RequestMapping("/eduService/teacher")
@Api(tags="讲师管理")
public class EduTeacherController {
@Autowired
private EduTeacherService teacherService;
//端口: http://localhost:8081/eduService/teacher/findAll
//1.查询讲师表的所有数据(rest风格)
@ApiOperation(value = "所有讲师列表")
@GetMapping("findAll")
public R finAllTeacher(){
//调用service方法查询所有的操作
List<EduTeacher> list = teacherService.list(null);
return R.ok().data("items",list);
}
//2.实现逻辑删除
@ApiOperation(value = "根据ID删除讲师")
@DeleteMapping("{id}")
public R removeById(@ApiParam(name = "id", value = "讲师ID", required = true)
@PathVariable String id){
boolean flag = teacherService.removeById(id);
if (flag){
return R.ok();
}else {
return R.error();
}
}
}
1.@Api注解可以用来标记当前Controller的功能。
2.@ApiOperation注解用来标记一个方法的作用。
3.@ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
4.如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
如:
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
@ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
}
5.需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。
6.如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码:
package com.gs.eduService.entity;
import com.baomidou.mybatisplus.annotation.*;
import java.util.Date;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;
/**
* <p>
* 讲师
* </p>
*
* @author testjava
* @since 2020-07-12
*/
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="EduTeacher对象", description="讲师")
public class EduTeacher implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "讲师ID")
private String id;
@ApiModelProperty(value = "讲师姓名")
private String name;
@ApiModelProperty(value = "讲师简介")
private String intro;
@ApiModelProperty(value = "讲师资历,一句话说明讲师")
private String career;
@ApiModelProperty(value = "头衔 1高级讲师 2首席讲师")
private Integer level;
@ApiModelProperty(value = "讲师头像")
private String avatar;
@ApiModelProperty(value = "排序")
private Integer sort;
//标明是逻辑删除的字段
@TableLogic
@ApiModelProperty(value = "逻辑删除 1(true)已删除, 0(false)未删除")
private Boolean isDeleted;
@ApiModelProperty(value = "创建时间")
private Date gmtCreate;
@ApiModelProperty(value = "更新时间")
private Date gmtModified;
}
[4] 浏览主页面,我们可以通过这些接口进行相关测试
http://localhost:8081/swagger-ui.html (端口号为自己boot项目的端口号)
以所有讲师列表为例:
小结
通过Swagger2提供的接口管理功能十分强大,不仅减轻了我们后端接口的维护,也方便了前端数据的获取。