目录

• 一、在SpringBoot项目中配置Swagger2
  • 1、pom.xml中对Swagger2的依赖
  • 2、编写配置类启用Swagger
  • 3、配置实体类的文档
  • 4、配置接口的文档
  • 5、访问文档
• 二、接口前后台分离的配置
  • 1、接口分离
  • 2、对前后台接口进行分组配置

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