Mooc項目開發筆記（三）：配置Swagger、統一返回結果

一、Swagger2介紹

前後端分離開發模式中，api文檔是最好的溝通方式。

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger 即可生成文檔，也可以對接口進行測試

它的好處是：

• 及時性 (接口變更後，能夠及時準確地通知相關前後端開發人員)
• 規範性 (並且保證接口的規範性，如接口的地址，請求方式，參數及響應格式和錯誤信息)
• 一致性 (接口信息一致，不會出現因開發人員拿到的文檔版本不一致，而出現分歧)
• 可測性 (直接在接口文檔上進行測試，以方便理解業務)

二、配置Swagger2

1、創建common模塊

在頂層模塊Mooc下創建模塊common（maven項目）

2、在common中引入相關依賴

	<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <scope>provided </scope>
        </dependency> 
        
	<!--mybatis-plus-->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <scope>provided </scope>
    </dependency>

    <!--lombok用來簡化實體類：需要安裝lombok插件-->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided </scope>
    </dependency>

    <!--swagger-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <scope>provided </scope>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <scope>provided </scope>
    </dependency>

    <!-- redis -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>

    <!-- spring2.X集成redis所需common-pool2
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-pool2</artifactId>
        <version>2.6.0</version>
    </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

<!--引入service_base子模塊-->
<dependency>
    <groupId>cn.hanzhuang42</groupId>
    <artifactId>service_base</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</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.hanzhuang42</groupId>
    <artifactId>common_utils</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</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，發現返回結果已經改變