Swagger

Swagger

Swagger简介

Swagger诞生的背景：

在前后端分离开发的情况下，前端开发人员经常抱怨后端开发人员给的接口文档与实际情况不一致。后端开发人员觉得编写接口文档太过于消耗精力，而且更新也不及时，以至于前后端开发人员经常出现争吵的情况，为了解决这个问题，Swagger应运而生。

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Swagger注解

@Api //修饰整个类，描述Controller的作用  

@ApiOperation //描述一个类中的一个方法

@ApiParam //单个参数的描述信息  

@ApiModel //用对象来接收参数  

@ApiModelProperty //用对象接收参数时，描述对象的一个字段  

@ApiResponse //HTTP响应其中1个描述  

@ApiResponses //HTTP响应整体描述  

@ApiIgnore //使用该注解忽略这个API  

@ApiError //发生错误返回的信息  

@ApiImplicitParam //一个请求参数  

@ApiImplicitParams //多个请求参数的描述信息

使用：

注：@ApiImplicitParams，@ApiImplicitParam注解已经不怎么使用了，因为太冗杂会降低开发效率，所以一般在创建实体类的时候使用@ApiModel注解和@ApiModelProperty来分别描述实体类对象的信息

@Data
@ApiModel(description = "用户信息")
public class User {

    @ApiModelProperty(value = "用户名", example = "lisi", required = true)
    private String username;

    @ApiModelProperty(value = "密码", example = "abcdef", required = true)
    private String password;

    @ApiModelProperty(value = "姓名", example = "李四", required = true)
    private String name;

    @ApiModelProperty(value = "头像", example = "abc.jpg")
    private String headIcon;
}
//============================================================================
@Data
@ApiModel(description = "用户查询的条件")
public class UserDto {

    @ApiModelProperty(value = "用户名", example = "admin")
    private String username;

    @ApiModelProperty(value = "姓名", example = "张三")
    private String name;

    @ApiModelProperty(value = "分页页码", example = "2", required = true)
    private int currentPage;

    @ApiModelProperty(value = "每页显示条数", example = "50", required = true)
    private int pageSize;
}

@Api(description = "用户管理接口")
@RestController
@RequestMapping("/user")
public class UserController {

    //这个注解是对当前这个接口进行说明
    @ApiOperation("查询用户")
    //Valid values are path, query, body, header or form.
//    @ApiImplicitParams(value = {
//            @ApiImplicitParam(name = "userDto",value = "查询的参数",
//                    dataTypeClass = UserDto.class, paramType="query")
//    })
//    @ApiResponses(value = {
//           @ApiResponse(code = 200, message = "OK"),
//           @ApiResponse(code = 401, message = "No Permission"),
//           @ApiResponse(code = 500, message = "Internal Error"),
//    })
    @GetMapping
    public List<User> getUsers(UserDto userDto){
        System.out.println(userDto);
        return new ArrayList<>();
    }

    @ApiOperation("添加用户")
    @PostMapping
    public int addUser(@RequestBody User user){
        System.out.println(user);
        return 1;
    }

    @ApiOperation("修改用户")
    @PutMapping
    public int updateUser(@RequestBody User user){
        System.out.println(user);
        return 1;
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/{username}")
    public int deleteUser(@PathVariable("username") String username){
        System.out.println(username);
        return 1;
    }
}

Swagger配置

@Configuration
@EnableSwagger2 //启用swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        //Docket类就是Swagger提供的一个与Spring MVC集成的配置类
        return new Docket(DocumentationType.SWAGGER_2) //文档类型设置为SWAGGER2
                .select() //选择当前文档类型进行构建
                .apis(RequestHandlerSelectors.basePackage("com.qfedu.controller")) //请求控制器包
                .paths(PathSelectors.any())//为任意请求构建API文档
                .build() //构建API
                .apiInfo(apiInfo()); //设置AIP文档的信息
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx项目接口文档")
                .description("xxx项目接口测试")
                .version("1.0.0")
                .termsOfServiceUrl("") //服务条款地址
                .license("") //许可证
                .licenseUrl("") //许可证URL
                .build();
    }
}

启动服务器，输入网址访问：http://localhost:9000/swagger-ui.html