在开发过程中,java后端需要与客户端进行交互,需要将后端的接口及参数写成文档给调用者查阅。一个问题也有此而生,需求改动频繁,接口设计也会随之改动,文档修改的不及时会带来很大的问题。
Swagger是一个自动生成文档的工具,可以在线查阅文档,减少了开发人员的负担,下面我们就来看看如何在SpringBoot中使用Swagger。
一、在SpringBoot项目中配置Swagger2
1、pom.xml中对Swagger2的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
复制代码
2、编写配置类启用Swagger
Swagger2Config.java
@Configuration //配置类
@EnableSwagger2 //启用Swagger2
public class Swagger2Config {
@Bean
public Docket apiConfig() {
return new Docket(DocumentationType.SWAGGER_2)//创建Swagger2类型的文档
.apiInfo(apiInfo());//apiInfo方法返回配置的接口信息
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("用户中心微服务前台网站API")//接口标题
.description("此文档描述了用户中心前台网站的基本API接口")//接口描述
.version("1.0")//接口版本
.contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))//联系方式:名字、网址、邮箱
.build();
}
}
复制代码
3、配置实体类的文档
实体类Member
//对实体名生成文档描述
@ApiModel(value="Member对象")
public class Member{
//对属性生成文档描述
@ApiModelProperty(value = "学员ID")
private Long memberId;
//required 将属性描述标记为必须
@ApiModelProperty(value = "手机号",required = true)
private String mobile;
@ApiModelProperty(value = "邮箱",required = true)
private String email;
@ApiModelProperty(value = "密码",required = true)
private String password;
@ApiModelProperty(value = "用户名")
private String userName;
//将不希望在文档中看到的属性使用hidden隐藏
@ApiModelProperty(value = "逻辑删除 1已删除 0未删除",hidden = true)
private Boolean deleted;
//省略其他字段
}
复制代码
4、配置接口的文档
控制器接口类
@RestController
//生成api接口的文档描述
@Api(description = "学员管理")
@RequestMapping("/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
//定义请求方法的名字和详细描述
@ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
@PostMapping
public boolean register(
//定义请求参数的文档描述 name的值是要描述的参数的名字
@ApiParam(name = "member", value = "学员对象", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
//省略其他
}
复制代码
5、访问文档
文档地址:localhost:8080/swagger-ui.html
二、接口前后台分离的配置
为什么要对接口进行前后台分离?因为前台和后台的功能有些相同,但有些差异,例如后台管理员可以删除用户,但前台是没有删除用户的功能的,将接口和文档分离更有利于管理维护。
1、接口分离
前台接口
@RestController
@Api(description = "前端学员管理")
@RequestMapping("/api/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
@PostMapping
public boolean register(
@ApiParam(name = "member", value = "学员对象", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
}
复制代码
后台接口放在同级下的admin包中
@RestController
@Api(description = "学员管理")
@RequestMapping("/admin/ucenter/member")
public class AdminMemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "返回所有学员列表")
@GetMapping
public List<Member> list() {
return memberService.list(null);
}
@ApiOperation(value = "根据id删除学员")
@DeleteMapping(value = "{memberId}")
public boolean deleteById(@ApiParam(name = "memberId", value = "学员id", required = true)
@PathVariable Long memberId) {
boolean result = memberService.removeById(memberId);
return result;
}
@ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
@PostMapping
public boolean register(
@ApiParam(name = "member", value = "学员对象", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
}
复制代码
这样就有了同一个实体的不同的接口
2、对前后台接口进行分组配置
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
//前台api接口文档
public Docket webApiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")//组名
.apiInfo(webApiInfo())
.select()//创建ApiSelectorBuilder对象
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))//过滤掉 admin 接口
.paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤掉 error 接口
.build();
}
@Bean
//后台管理员api文档
public Docket adminApiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()//创建ApiSelectorBuilder对象
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))//只显示 admin 接口
.build();
}
private ApiInfo webApiInfo() {
return new ApiInfoBuilder()
.title("用户中心微服务前台网站API")
.description("此文档描述了用户中心前台网站的基本API接口")
.version("1.0")
.contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))
.build();
}
private ApiInfo adminApiInfo() {
return new ApiInfoBuilder()
.title("用户中心微服务后台管理系统的API")
.description("此文档描述了用户中心后台管理系统的基本API接口")
.version("1.0")
.contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))
.build();
}
}
复制代码