接口调试神器——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

image

注解修饰

@API

类级注解，说明该类的作用；

@Api(tags = {"a", "b"}, description = "描述")

效果图示：

image

@ApiOperation

方法级注解，说明该方法的作用；

@ApiOperation(value = "获取资源", notes = "请注意")

效果图示：

image

@ApiImplicitParams @ApiImplicitParam

方法级注解，描述接口（一组）参数；

@ApiOperation(value = "获取资源", notes = "请注意")
@ApiImplicitParams({
    @ApiImplicitParam(paramType = "query", name = "name", value = "查询名称", required = true, dataType = "string"),
    @ApiImplicitParam(paramType = "query", name = "type", value = "查询类别", dataType = "int"),
})

效果图示：

image

@ApiResponses @ApiResponse

方法级注解，描述接口（一组）响应码描述；

@ApiResponses({
    @ApiResponse(code = 500, message = "服务器异常")
})

效果图示：

image

@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;
}

效果图示：

image

功能测试

image

自定义主题

官方UI可能不太符合部分审美，推荐一款国人开源项目：https://github.com/caojiantao/swagger-ui-layer

使用非常简单，引入依赖：

<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

效果图示：

image

接口文档导出

Mock数据

导出接口JSON文件

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

YApi平台

添加项目

image

导入JSON接口，同步数据

image

操作成功

image

生产环境去除

swagger.enable=true

参考文章

1. Swagger官网