Swagger2—整合SpringBoot

一、Swagger

用于生成服务器接口的规范文档的工具，并且能够对接口进行测试的工具

1.1 作用

• 生成接口说明文档
• 对接口进行测试

1.2 整合

• 添加依赖（Swagger2、Swagger UI） 在controller模块添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
 
 

• 在Controller模块中创建Swagger的配置（Java配置方式）

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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//配置类
@Configuration
//开启依赖
@EnableSwagger2
public class SwaggerConfig {
    /*Swagger会帮助我们生成接口文档
    * 1.配置生成的文档信息
    * 2.配置生成规则
    */
    /*必须初始的一个对象Docket
    * Docket封装接口文档信息
    */
    @Bean
    public Docket getDocket(){
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("商城后端接口说明")
            .description("这是一个接口规范详细")
            .version("版本：V 1.0.0")
            .contact(new Contact("万万","www.wan.com","2287228119@qq.com"));
        //如何获取接口、抽象类对象
        //new 接口，需要在构造器后的（）实现接口中的所有抽象方法
        //new 子类/实现类
        //工厂模式
        ApiInfo apiInfo =apiInfoBuilder.build();
        Docket docket=new Docket(DocumentationType.SWAGGER_2)//文档风格
            .apiInfo(apiInfo)//指定生成的文档中的页面信息：文档标题、版本、作者
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wan.controller"))//对那个包的类生成文档
            .paths(PathSelectors.any())//.regex("/user/")只会对user的请求产生说明
            .build();
 
        return docket;
    }
 
}
 

访问http://localhost:8080/swagger-ui.html

• swagger 3.0.0集成stater

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

只需在上述配置类加上替换@EnableOpenApi

访问的网址为：http://localhost:8080/swagger-ui/index.html

1.3 Swagger注解说明

Swagger提供了一套注解，可以对每个接口详细描述

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

@Api(value = "提供商品添加、修改、删除及查询的相关接口",tags = "商品管理")

@ApiOperation方法注解：说明接口方法的作用

@ApiImplicitParam和ApiImplicitParams方法注解，说明接口方法的参数

@RestController
@RequestMapping("/user")
@Api(value = "提供用户登录和注册接口",tags = "用户管理")
public class UserController {
    @Autowired
    private UserService userService;
    @ApiOperation("用户登录接口")
    @ApiImplicitParams({
        @ApiImplicitParam(type= "string",name = "username",value = "用户登录账号",required = true),
        @ApiImplicitParam(type = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "123456")
    })
    @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVo login(@RequestParam("username") String name,
                          @RequestParam(value = "password",defaultValue = "123456")String pwd){
        return userService.checkLogin(name,pwd);
    }
    @RequestMapping(value = "/regist",method = RequestMethod.POST)
    public ResultVo regist(User user){
        return new ResultVo(1000,"Success",null);
    }
 
}
 

@ApiModel和@ApiModelProperty 当接口参数和返回值信息为对象类型时，在实体类中添加注解说明

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户信息",description = "用户/卖家信息")
public class User {
    @ApiModelProperty(dataType = "int",required = false,example ="0")
    private int userId;
    @ApiModelProperty(dataType = "string",required = true,value = "用户注册账号")
    private String userName;
    @ApiModelProperty(dataType = "string",required = true,value = "用户注册密码")
    private String userPwd;
    @ApiModelProperty(dataType = "string",required = true,value = "用户头像的url")
    private String userImg;
}

@ApiIgnore 接口方法注解,添加此注解的方法将不会生成到接口文档中

1.4 Swagger-ui插件

• 导入依赖

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

• 测试访问 http://localhost:8080/doc.html