学会了Swagger，再也不用PostMan做接口测试了

说到swagger，你第一反应想到的是什么呢？是不是这首洗脑神曲。

我们说的swagger当时不是这个洗脑神曲了。

swagger是一款API框架，用于开发中接口测试使用的。提供了丰富的注解，方便我们在开发中生成api接口文档以及做接口测试。学会了swagger，再也不需要postman等接口测试工具 了。

简介

官网：https://swagger.io/

• 借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。使用Swagger可以帮助您大规模设计和记录API。

• 只要导入项目中，就可以在线访问。

• 可以在线生成Resutful Api文档。

SpringBoot集成Swagger

添加依赖

继承swagger，只需要导入两个依赖作标即可（在此之前，需要先创建一个springboot项目，以及导入web相关依赖，以便之后进行测试使用。）

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

下面是博主测试使用时的依赖包

因为用到了Lombok，所以IDE得装上Lombok插件才能用，否则可以选择移除

<properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>

运行项目

当你导入好依赖作标后，就已经开始可以使用了。swagger进行了一些默认配置。

访问/swagger-ui.html这个地址即可。

例如是在本地的8080端口运行的话，就访问localhost:8080/swagger-ui.html

出现这么个界面就可以正常使用了。

• A：关于接口文旦的说明介绍
• B：分组信息
• C：项目中需要测试的api接口
• D：模型类

接下来说说改如何修改配置上面提到的4个信息

Swagger配置

swagger配置需要用Docket实例。

1、创建一个SwaggerConfig.java，加上@EnableSwagger2表示开启swagger

package cn.jxj4869.swaggerstart.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
public class SwaggerConfig {
    
    

}

2、创建Docket实例

    @Bean
    public Docket docket() {
    
    
        return new Docket(DocumentationType.SWAGGER_2);
    }

构造函数需要传入DocumentationType。通过源码可以看到DocumentationType给我们提供了三个常量，而我们使用的是swagger2。所以就选择SWAGGER_2。

public class DocumentationType extends SimplePluginMetadata {
    
    
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
    private final MediaType mediaType;

3、通过ApiInfo修改Document也就是A部分（上面那个图）的信息。

    @Bean
    public Docket docket() {
    
    
        Contact contact = new Contact("jiangxiaoju", "https://blog.csdn.net/qq_43058685", "邮箱");
        ApiInfo apiInfo = new ApiInfo(
                "Swagger配置", // 标题
                "Swagger演示信息", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_43058685", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo);
    }

配置好后重启项目。

4、通过Docket中的select()配置swagger扫描接口的范围。

默认是扫描整个项目中的api接口。所以在C部分才会显示一个basic-error-controller接口。如果我们只需要我们自己项目下的api接口信息。可以通过下面这个配置来实现

    @Bean
    public Docket docket() {
    
    
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        ApiInfo apiInfo = new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .build()
                ;
    }

RequestHandlerSelectors 可以配置扫描的方式。主要有以下几种

• any：就是扫描所有的接口
• none：所有接口都不扫描
• basePackage：需要传入一个包名，会扫描该包名下所有的接口

除此之外还可以用path对扫描路径进行过滤

    @Bean
    public Docket docket() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 扫描以jxj4869开头的接口 
                .build()
                ;
    }

5、配置swagger的开关

    @Bean
    public Docket docket() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
            // 选择是否开启swagger 。true为开启，false为关闭
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 扫描以jxj4869开头的接口
                .build()
                ;
    }

6、配置分组信息

当一个项目需要多个人开发时，每个人负责各自实现的接口。这时候就需要他们可以各自写api接口文档。

通过Docket的groupName()方法设置组名

    @Bean
    public Docket docket() {
    
    

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .groupName("组1")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
                .paths(PathSelectors.ant("/jxj4869/**"))  // 扫描以jxj4869开头的接口
                .build()
                ;
    }

如果有多个组的话，可以实例化多个Docket放到容器中就行。

常用注解

下面为swagger中常用的注解，具体用法参考后面的说明

Swagger注解	简单说明
@Api(tags = “模块说明”)	作用在模块类上
@ApiOperation(“接口说明”)	作用在接口方法上
@ApiModel(“模型类说明”)	作用在模型类上：如VO、BO
@ApiModelProperty( “模型属性说明”)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“接口方法参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty
@ApiImplicitParam	类似于@ApiParam，可以作用在类方法上
@ApiImplicitParams	可以放多个@ApiImplicitParam

这里说下@ApiParam和@ApiImplicitParam使用时的区别。

• 用@ApiParam备注的参数，参数类型是application/json。适合用在Post等请求类型上。
• 用@ApiImplicitParam备注的参数，参数类型时query。

所以要在get类型的请求接口上，不要使用@ApiParam

模型注解使用

先定义个user类。

• @Data：Lombok中的注解，用于生成getter和setter
• @Accessors：Lombok中的注解，可以使用链式调用

解析来两个注解就是swagger中的

• @ApiModel：用来给模型添加描述。
• @ApiModelProperty：作用在模型属性上，常用的就是备注属性信息。还有可以其他的可选参数，可以参考源码进行使用，例如显示变量的类型，是否显示该备注等。

package cn.jxj4869.swaggerstart.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;

import java.util.Date;


@ApiModel("用户类")
@Data
@Accessors(chain = true)
public class User {
    
    

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;


    @ApiModelProperty("日期")
    private Date date;
}

配置好重启项目后，就可以看到

Api接口的调用

在使用api接口之前，先在controller上，加上一些注解。

package cn.jxj4869.swaggerstart.controller;

import cn.jxj4869.swaggerstart.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@RestController
@Api("这是一个Hello Controller")
public class HelloController {
    
    


    @GetMapping("/hello")
    @ApiOperation("这会返回一个User信息")
    @ApiImplicitParams({
    
    
            @ApiImplicitParam(name = "username",value = "用户名"),
            @ApiImplicitParam(name = "password",value = "密码"),}
    )
    public User test(String username, String password) {
    
    

        return new User().setPassword(password).setUsername(username).setDate(new Date());
    }

}

配置好后，效果如图所示

如果一个方法明确了是使用什么类型的请求，例如上面的代码用了@GetMapping，只能用get请求，所以下面就只显示了一个api接口

但是如果使用了@RequestMapping，但是没有明确指明用哪种类型的请求，会把所有的请求类型接口都列出来

接下来测试使用接口

点击右上角的 try it out后，输入对应的参数。点execute就行可以执行力

上面使用了Get方式的请求，接下来我们来试下Post请求方式

   @PostMapping("/hello")
    @ApiOperation("这会返回一个User信息")
    public User test1(@ApiParam("用户名") String username,@ApiParam("密码") String password) {
    
    

        return new User().setPassword(password).setUsername(username).setDate(new Date());
    }

到此Swagger常用方法也都介绍完了，别忘了留下一键三连再走。