在开发过程中，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(); } }