接口調試神器——Swagger

Swagger介紹

最好的API構建工具。

1. 自動生成在線接口文檔；
2. 集成接口在線調試；
3. 使用很是簡單；
4. 社區活躍；

Hello World

以springboot工程爲例；

添加swagger依賴

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>
複製代碼

編寫Swagger配置

package com.iflytek.demo.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/** * @author caojiantao * @mail: jtcao2@iflytek.com * @description: swagger配置類 * @date 2018/10/30 17:18 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket swaggerPlugin() {
        List<Parameter> parameters = new ArrayList<>();
        Parameter token = new ParameterBuilder()
                .name("X-Token")
                .description("登錄令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .build();
        parameters.add(token);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iflytek.demo"))
                .build()
                .globalOperationParameters(parameters);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger入門示例")
                .description("一些藉口描述")
                .version("1.0")
                .build();
    }
}
複製代碼

編寫測試接口

package com.iflytek.demo.swagger;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/** * @author caojiantao * @mail: jtcao2@iflytek.com * @description: 一句話描述這個類 * @date 2018/11/1 14:51 */
@RestController
public class TestController {

    @GetMapping("/get")
    public ResultDTO get(Query query) {
        System.out.println(query);
        return new ResultDTO<>(200, "88888888", "get請求成功");
    }

    @PostMapping("/post")
    public ResultDTO post(@RequestBody Query query) {
        System.out.println(query);
        return new ResultDTO<>(200, "88888888", "post請求成功");
    }
}
複製代碼

hello world

運行項目，進入swagger-ui頁面：http://127.0.0.1:8080/swagger-ui.html

註解修飾

@API

類級註解，說明該類的做用；

@Api(tags = {"a", "b"}, description = "描述")
複製代碼

效果圖示：

@ApiOperation

方法級註解，說明該方法的做用；

@ApiOperation(value = "獲取資源", notes = "請注意")
複製代碼

效果圖示：

@ApiImplicitParams @ApiImplicitParam

方法級註解，描述接口（一組）參數；

@ApiOperation(value = "獲取資源", notes = "請注意")
@ApiImplicitParams({
    @ApiImplicitParam(paramType = "query", name = "name", value = "查詢名稱", required = true, dataType = "string"),
    @ApiImplicitParam(paramType = "query", name = "type", value = "查詢類別", dataType = "int"),
})
複製代碼

效果圖示：

@ApiResponses @ApiResponse

方法級註解，描述接口（一組）響應碼描述；

@ApiResponses({
    @ApiResponse(code = 500, message = "服務器異常")
})
複製代碼

效果圖示：

@ApiModel @ApiModelProperty

類級註解，詳細描述一個model；

@ApiModel(value = "響應實體")
public class ResultDTO<T> implements Serializable {

    @ApiModelProperty(value="響應碼",name="code",example="200")
    private Integer code;
    private  T data;
    private String message;
}
複製代碼

效果圖示：

功能測試

自定義主題

官方UI可能不太符合部分審美，推薦一款國人開源項目：github.com/caojiantao/…

使用很是簡單，引入依賴：

<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.0.0</version>
</dependency>

複製代碼

訪問地址：http://127.0.0.1:8080/docs.html

效果圖示：

接口文檔導出

Mock數據

導出接口JSON文件

http://127.0.0.1:8080/v2/api-docs

YApi平臺

添加項目

導入JSON接口，同步數據

操做成功

生產環境去除

swagger.enable=true

參考文章

1. Swagger官網