Mooc项目开发笔记（三）：配置Swagger、统一返回结果

一、Swagger2介绍

前后端分离开发模式中，api文档是最好的沟通方式。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 即可生成文档，也可以对接口进行测试

它的好处是：

• 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
• 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
• 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
• 可测性 (直接在接口文档上进行测试，以方便理解业务)

二、配置Swagger2

1、创建common模块

在顶层模块Mooc下创建模块common（maven项目）

2、在common中引入相关依赖

	<dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
            <scope>provided scope>
        dependency> 
        
	
    <dependency>
        <groupId>com.baomidougroupId>
        <artifactId>mybatis-plus-boot-starterartifactId>
        <scope>provided scope>
    dependency>

    
    <dependency>
        <groupId>org.projectlombokgroupId>
        <artifactId>lombokartifactId>
        <scope>provided scope>
    dependency>

    
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger2artifactId>
        <scope>provided scope>
    dependency>
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger-uiartifactId>
        <scope>provided scope>
    dependency>

    
    <dependency>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-data-redisartifactId>
    dependency>

    
dependencies>

3、在common下面创建子模块service-base

删除common的src目录，并在其下创建service_base模块

4、在模块service-base中，创建swagger的配置类

@Configuration
@EnableSwagger2
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("Mooc网站-课程中心API文档")
                .description("本文档描述了Mooc网站课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("Miracle42", "http://www.****42.cn", "****@qq.com"))
                .build();
    }
}

5、在模块service模块中引入service-base

<dependency>
    <groupId>cn.hanzhuang42groupId>
    <artifactId>service_baseartifactId>
    <version>0.0.1-SNAPSHOTversion>
dependency>

6、在service-edu启动类上添加注解属性

//设置在该包下进行组件扫描
//这样只要包名一样，其他模块的Component也可以被扫描到
@SpringBootApplication(scanBasePackages = "cn.hanzhuang42")
public class EduApplication {

    public static void main(String[] args) {
        SpringApplication.run(EduApplication.class, args);
    }

}

7、定义接口说明和参数说明

• 定义在类上：@Api
• 定义在方法上：@ApiOperation
• 定义在参数上：@ApiParam

@Api(description="讲师管理")
@RestController
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    @Autowired
    EduTeacherService teacherService;

    //查询所有
    @ApiOperation(value = "获取所有讲师列表")
    @GetMapping("findAll")
    public List<EduTeacher> finaAll() {
        List<EduTeacher> list = teacherService.list(null);
        return list;
    }

    //逻辑删除讲师
    @ApiOperation(value = "根据id逻辑删除讲师")
    @DeleteMapping("{id}")
    public boolean deleteById(
            @ApiParam(name = "id", value = "讲师ID", required = true)
            @PathVariable("id") String id) {
        boolean success = teacherService.removeById(id);
        return success;
    }
}

8、定义实体类属性说明

例如：

@ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00")
private Date gmtCreate;

@ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00")
private Date gmtModified;

9、运行应用并访问

启动应用

访问：swagger

接下来点击一个API可以看到下面的页面，在该页面中点击Try it out 还可以直接进行测试。

三、统一返回结果对象

1、统一返回数据格式

项目中我们会将响应封装成json返回，一般我们会将所有接口的数据格式统一， 使前端(iOS Android, Web)对数据的操作更一致、轻松。

一般情况下，统一返回数据格式没有固定的格式，只要能描述清楚返回的数据状态以及要返回的具体数据就可以。但是一般会包含状态码、返回消息、数据这几部分内容

例如，我们的系统要求返回的基本数据格式如下：

列表：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "items": [
      {
        "id": "1",
        "name": "刘德华",
        "intro": "毕业于师范大学数学系，热爱教育事业，执教数学思维6年有余"
      }
    ]
  }
}

分页：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "total": 17,
    "rows": [
      {
        "id": "1",
        "name": "刘德华",
        "intro": "毕业于师范大学数学系，热爱教育事业，执教数学思维6年有余"
      }
    ]
  }
}

没有返回数据：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {}
}

失败：

{
  "success": false,
  "code": 20001,
  "message": "失败",
  "data": {}
}

因此，我们定义统一结果

{
  "success": 布尔, //响应是否成功
  "code": 数字, //响应码
  "message": 字符串, //返回消息
  "data": HashMap //返回数据，放在键值对中
}

2、创建统一结果返回类

1）在common模块下创建子模块common-utils

2）创建接口定义返回码

public interface ResultCode {

    Integer SUCCESS = 20000; //成功

    Integer ERROR = 20001;  //失败

}

3）创建结果类

创建类 R.java

//统一返回结果类
@Data
public class R {

    @ApiModelProperty(value = "是否成功")
    private boolean success;

    @ApiModelProperty(value = "返回码")
    private int code;

    @ApiModelProperty(value = "返回消息")
    private String msg;

    @ApiModelProperty(value = "返回数据")
    private Map<String, Object> data = new HashMap<>();

    //构造方法私有化
    private R() {}

    //成功的返回结果
    public static R ok(){
        R r = new R();
        r.setSuccess(true);
        r.setCode(ResultCode.SUCCESS);
        r.setMsg("成功");
        return r;
    }

    //失败的返回结果
    public static R error(){
        R r = new R();
        r.setSuccess(false);
        r.setCode(ResultCode.ERROR);
        r.setMsg("失败");
        return r;
    }


    public R success(Boolean success){
        this.setSuccess(success);
        return this;
    }

    public R message(String message){
        this.setMsg(message);
        return this;
    }

    public R code(Integer code){
        this.setCode(code);
        return this;
    }

    public R data(String key, Object value){
        this.data.put(key, value);
        return this;
    }

    public R data(Map<String, Object> map){
        this.setData(map);
        return this;
    }
}

3、统一返回结果使用

1）在service模块中添加依赖

<dependency>
    <groupId>cn.hanzhuang42groupId>
    <artifactId>common_utilsartifactId>
    <version>0.0.1-SNAPSHOTversion>
dependency>

2）修改Controller中的返回结果

//查询所有
@ApiOperation(value = "获取所有讲师列表")
@GetMapping("findAll")
public R finaAll() {
    List<EduTeacher> list = teacherService.list(null);
    return R.ok().data("items", list);
}

//逻辑删除讲师
@ApiOperation(value = "根据id逻辑删除讲师")
@DeleteMapping("{id}")
public R deleteById(
        @ApiParam(name = "id", value = "讲师ID", required = true)
        @PathVariable("id") String id) {
        boolean success = teacherService.removeById(id);
    if (success) {
        return R.ok();
    } else {
        return R.error();
    }
}

3）在Swagger中测试

重启项目

在Swagger中测试API，发现返回结果已经改变