SpringBoot整合Swagger

前后端分离开发，后端需要编写接口说明文档，会耗费比较多的时间，Swagger是一个用于生成服务器接口的规范性文档，并且能够对接口进行测试的工具。

作用

• 生成接口说明文档

• 对接口进行测试

整合

• 添加依赖（Swagger2\Swagger UI）

    <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>
  

• 在api子工程创建Swagger的配置类。

  • 配置生成的文档信息

  • 配置生成规则

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){

        //创建封面信息对象
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("接口说明")
                .description("This document declares the project backend interface specification.")
                .version("version")
                .contact(new Contact("Author","url","Email"));
        ApiInfo apiInfo = apiInfoBuilder.build();

        //指定生成策略
        Docket docket = new Docket(DocumentationType.SWAGGER_2)//指定文档风格
            .apiInfo(apiInfo)//指定生成的文档中的封面信息：文档标题，版本，作者
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))//指定生成接口文档的包
                .paths(PathSelectors.any())
                .build();

        return docket;
    }
}

• 测试

  • 启动项目，访问 localhost:8080/swagger-ui.html

Swagger注解说明

swagger提供了一套注解，可以对每个接口进行详细说明。

@Api 类注解，在控制器类添加此注解，可以对控制器进行功能说明。

@Api(value = "提供用户的登录接口",tags = "用户管理")

@ApiOperation，在控制器中的方法上添加，对方法功能进行说明。

@ApiOperation(value = "用户登录接口")
public ResultVO login(String name,String pwd){}

@ApiImplicitParams，@ApiImplicitParam，用在控制器方法上，对参数进行说明。

@ApiOperation(value = "用户登录接口")
@ApiImplicitParams({
        @ApiImplicitParam(name = "name",value = "登录账号",required = true,dataType = "String"),
        @ApiImplicitParam(name = "pwd",value = "登录密码",required = true,dataType = "String")
})
public ResultVO login(String name,String pwd){
    return userService.checkLogin(name, pwd);
}

@ApiModel，@ApiModelPrope用在实体类中，对实体类进行说明。

@ApiModel(value = "ResultVO对象",description = "封装接口返回给前端的数据")
public class ResultVO {
    //响应给前端的状态码
    @ApiModelProperty(value = "响应状态码",dataType = "int")
    private int code;
    //提示信息
    @ApiModelProperty("响应提示信息")
    private String msg;
    //数据
    @ApiModelProperty("响应数据")
    private Object data;
}

@ApiIgnore，文档生成时将跳过带有此注解的接口。

Swagger UI插件

• 导入插件依赖。

  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.6</version>
  </dependency>
  

• 访问 localhost:8080/doc.html