摘要：前言目前互聯(lián)網(wǎng)開發(fā)市場都流行前后臺真正的分離，后臺提供數(shù)據(jù)接口，前臺負(fù)責(zé)請求數(shù)據(jù)并渲染。今天就介紹一款將接口文檔編寫和測試合并一起的集大成者，也是目前很多企業(yè)再用的一個管理工具。

前言：目前互聯(lián)網(wǎng)開發(fā)市場都流行前后臺真正的分離，后臺提供數(shù)據(jù)API接口，前臺負(fù)責(zé)請求數(shù)據(jù)并渲染。那么我們程序猿們在編寫接口的時候，最不方便之處就是寫完接口后需要進(jìn)行文檔的編寫以及接口的測試。今天就介紹一款將接口文檔編寫和測試合并一起的集大成者Swagger，也是目前很多企業(yè)再用的一個API管理工具。此DEMO的開發(fā)環(huán)境是：MAVEN + Spring Boot 2.1.0 + JDK8 + Swagger2.9.2

在https://start.spring.io/中選...，然后選用Spring Boot2.1.0版本，Group是com.mage，Artifact是swagger_restful，Dependencies選擇web，這樣就能快速構(gòu)建一個基于Spring Boot的web項目了。如下圖：

解壓swagger_restful.zip，然后使用idea導(dǎo)入項目，并執(zhí)行SwaggerRestfulApplication.java，不報錯說明項目構(gòu)建成功

    io.springfox
    springfox-swagger2
    2.9.2




    io.springfox
    springfox-swagger-ui
    2.9.2

其中springfox-swagger2這個jar包是用于JSON API文檔的生成，springfox-swagger-ui用于API文檔界面生成，其他版本請參考：https://mvnrepository.com/art...://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

編寫一個Test的數(shù)據(jù)模型

package com.mage.swagger_restful.model;

public class Test {
    private Integer id;
    private String content;
    private Integer isValid;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }

    public Integer getIsValid() {
        return isValid;
    }

    public void setIsValid(Integer isValid) {
        this.isValid = isValid;
    }
}

基于Restful規(guī)則，編寫一組測試的API接口：

package com.mage.swagger_restful.controller;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("test")
public class TestController {

    @GetMapping("")
    public String list() {
        return "查詢列表數(shù)據(jù)!";
    }

    @GetMapping("{id}")
    public String find(@PathVariable Integer id) {
        return String.format("根據(jù)主鍵查詢數(shù)據(jù): %d", id);
    }

    @PostMapping("")
    public String add() {
        return "插入數(shù)據(jù)!";
    }

    @PutMapping("{id}")
    public String update(@PathVariable Integer id) {
        return String.format("根據(jù)主鍵更新一條記錄: %d", id);
    }

    @DeleteMapping("{id}")
    public String delete(@PathVariable Integer id) {
        return String.format("根據(jù)主鍵刪除記錄: %d", id);
    }
}

因為接口是基于Restful(本文不討論Restful的編寫規(guī)范)編寫，所以如果單純利用瀏覽器輸入是沒法進(jìn)行接口測試的，比如模擬post, put或者delete請求，這時要測試可以借助一些瀏覽器的插件比如postman或者rested等。這樣我們還要額外去安裝工具，顯得比較麻煩，同時工作中寫完接口后，一般還會編寫接口文檔，那么聰明的碼農(nóng)就想著能不能優(yōu)化這個流程，讓接口測試和接口文檔編寫變得簡單快捷，于是乎，swagger應(yīng)用而生。

package com.mage.swagger_restful.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {

    @Bean
    public Docket createDocket(){

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("碼歌學(xué)院API")
                        .description("碼歌學(xué)院相關(guān)接口API文檔")
                        .version("1.0").build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mage"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

其中@EnableSwagger2開啟Swagger2功能，是swagger2的注解，@ConditionalOnExpression("${swagger.enable:true}")當(dāng)配置文件中swagger.enable為true時才啟用swagger2，是spring boot注解，方便區(qū)分不同環(huán)境下是否啟用swagger2。

swagger.enable=true

修改Test實體模型：

package com.mage.swagger_restful.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "測試模型實體")
public class Test {
    @ApiModelProperty(name = "id", value = "主鍵", hidden = true)
    private Integer id;
    @ApiModelProperty(name = "content", value = "測試內(nèi)容")
    private String content;
    @ApiModelProperty(name = "isValid", value = "是否有效0=無效，1=有效", hidden = true)
    private Integer isValid;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }

    public Integer getIsValid() {
        return isValid;
    }

    public void setIsValid(Integer isValid) {
        this.isValid = isValid;
    }
}

其中：

@ApiModel(description = "測試模型實體")作用在參數(shù)實體或者響應(yīng)實體上，description代表描述信息；

@ApiModelProperty(name = "id", value = "主鍵", hidden = true)作用在實體屬性上，標(biāo)記屬性名稱和說明內(nèi)容，name代表屬性名稱，value表示屬性內(nèi)容，hidden是否因此，默認(rèn)是false。

修改TestController：

package com.mage.swagger_restful.controller;

import com.mage.swagger_restful.model.Test;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("test")
@Api(tags = "測試API接口")
public class TestController {

    @GetMapping("")
    @ApiOperation(value="獲取列表數(shù)據(jù)", notes="獲取列表下測試數(shù)據(jù)")
    public String list() {
        return "查詢列表數(shù)據(jù)!";
    }

    @GetMapping("{id}")
    @ApiOperation(value="獲取ID數(shù)據(jù)", notes="根據(jù)ID獲取某條測試數(shù)據(jù)")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String find(@PathVariable Integer id) {
        return String.format("根據(jù)主鍵查詢數(shù)據(jù): %d", id);
    }

    @PostMapping("")
    @ApiOperation(value="新增數(shù)據(jù)")
    @ApiParam(name = "test", value = "添加的測試模型實體")
    public String add(@RequestBody Test test) {
        return "插入數(shù)據(jù)!";
    }

    @PutMapping("{id}")
    @ApiOperation(value="更新數(shù)據(jù)", notes="根據(jù)ID更新測試數(shù)據(jù)")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String update(@PathVariable Integer id, @ApiParam(name = "test", value = "更新的測試模型實體") @RequestBody Test test) {
        return String.format("根據(jù)主鍵更新一條記錄: %d", id);
    }

    @DeleteMapping("{id}")
    @ApiOperation(value="刪除數(shù)據(jù)", notes="根據(jù)ID刪除測試數(shù)據(jù)")
    @ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)
    public String delete(@PathVariable Integer id) {
        return String.format("根據(jù)主鍵刪除記錄: %d", id);
    }
}

其中：

@Api(tags = "測試API接口")標(biāo)記controller類是做什么的，tags表示分類；

@ApiOperation(value="獲取列表數(shù)據(jù)", notes="獲取列表下測試數(shù)據(jù)")標(biāo)記controller下的方法，表示這個接口是做什么的，value就是說明作用，notes詳細(xì)說明；

@ApiImplicitParam(name = "id", value = "主鍵id", paramType = "path", required = true)標(biāo)記參數(shù)，name是參數(shù)名，value是參數(shù)說明，paramType是參數(shù)類型：path(路徑參數(shù)),query(查詢參數(shù)), body(請求體參數(shù))，header(請求頭參數(shù))，form(表單提交參數(shù))，require代表是否必填，默認(rèn)是false

@ApiParam(name = "test", value = "更新的測試模型實體")跟@ApiImplicitParam類似，標(biāo)記參數(shù)，不過不同的是：

對Servlets或者非 JAX-RS的環(huán)境，只能使用 ApiImplicitParam。

在使用上，ApiImplicitParam比ApiParam具有更少的代碼侵入性，只要寫在方法上就可以了，但是需要提供具體的屬性才能配合swagger ui解析使用。

ApiParam只需要較少的屬性，與swagger ui配合更好。

點開測試API接口就可以進(jìn)行測試：

如果采用swagger2.9.0時，會出現(xiàn)一個bug，比如我修改一下TestController里面的find方法

舊方法：

新方法：

這時如果啟動，訪問swagger ui時會出現(xiàn)一個bug：

這個是一個數(shù)據(jù)類型轉(zhuǎn)化的錯誤，就是因為我設(shè)置了id為int類型，而swagger默認(rèn)給的是空字符串，因此就提示錯誤，解決方案有兩種，第一種就是不要寫dataType，第二種就是升級swagger-annotations和models jar包：

a）排除已經(jīng)依賴的swagger-annotations和models jar包

    io.springfox
    springfox-swagger2
    2.9.2
    
        
            io.swagger
            swagger-annotations
        
        
            io.swagger
            swagger-models
        
    

b) 引入新的jar包

    io.swagger
    swagger-annotations
    1.5.21


    io.swagger
    swagger-models
    1.5.21

這樣也能完美解決！