Swagger框架学习

Swagger

第 1 节 Swagger 简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要为前端开发人员提供后端接口的一个可视化文档。

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

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

Swagger 的劣势：

• 待配置的注解过多，影响代码维护。

第 2 节 Swagger 依赖及配置

2.1 Swagger2 依赖

导入以下依赖，需要额外设置 Swagger 配置类。注意依赖版本不要太高，容易出现 bug。

<!--Swagger2 依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!--Swagger2 ui依赖，官方ui界面-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

springfox-swagger2：这个组件的功能用于帮助我们自动生成描述 API 的 json 文件。

springfox-swagger-ui：就是将描述 API 的 json 文件解析出来，用一种更友好的方式呈现出来。

<!--Swagger2 ui依赖，bootstrap ui界面-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

ui 界面一个就可以。

2.2 Swagger2 配置

Swagger 配置类：

package com.luochen.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author 洛尘大大
 * @projectName SpringBoot
 * @title SwaggerConfig
 * @Date 2021/11/2 11:45
 * @Description Swagger配置
 */
// 设置该类为配置类
@Configuration
// 开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 配置Swagger bean实例
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 表示扫描controller层
                .apis(RequestHandlerSelectors.basePackage("com.luochen.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置SwaggerAPI信息
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后端接口文档")
                .description("为前端提供好的后端接口文档")
                .version("1.0")
                .build();
    }
}

配置好后，则根据 http://localhost:8080/swagger-ui.html 进行访问。

第 3 节 常用注解

Swagger2 是通过扫描很多的注解来获取数据帮我们展示在 ui 界面上的，下面就介绍下常用的注解。

3.1 @Api

@Api()：用在请求的类上，表示对类的说明，也代表了这个类是 Swagger2 的资源。

参数说明：

tags: 说明该类的作用，参数是个数组，可以填多个。
value = "该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

@RestController
@Api(tags = "StudentController", value = "学生操作控制器", description = "学生操作接口")
public class StudentController {}

3.2 @ApiOperation

@ApiOperation()：用于方法，表示一个 http 请求访问该方法的操作。

参数说明：

value = "方法的用途和作用"    
notes = "方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

@ApiOperation(value = "获得所有学生信息")
@GetMapping("/getAllStudents")
public Object getAllStudents() {
    List<Student> students = studentMapper.selectAllStudents();
    return students;
}

3.3 @ApiModel

@ApiModel()：用于响应实体类上，用于说明实体作用。

参数说明：

description = "描述实体的作用"  

3.4 @ApiModelProperty

@ApiModelProperty：用在属性上，描述实体类的属性。

参数说明：

value = "用户名"  描述参数的意义
name = "name"    参数的变量名
required = true     参数是否必选

3.5 @ApiImplicitParams

@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam。

3.6 @ApiImplicitParam

@ApiImplicitParam：用于方法，表示单独的请求参数。

参数说明：

name = "参数名" 
value = "参数说明" 
dataType = "数据类型" 
paramType = "query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue = "参数的默认值"
required = "true" 表示参数是否必须传

@ApiOperation(value = "按照id查找学生信息")
@ApiImplicitParam(name = "id",value = "学生id",dataType = "String",paramType = "path",required = true)
@GetMapping("/getStudent/{id}")
public Object getStudent(@PathVariable String id) {
    Student student = studentMapper.selectStudent(id);
    return student;
}

3.7 @ApiParam

@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明。

参数说明：

name = "参数名称"
value = "参数的简要说明"
defaultValue= "参数默认值"
required = "true" 表示属性是否必填，默认为false

3.8 @ApiResponses

@ApiResponses：用于请求的方法上，根据响应码表示不同响应。

一个 @ApiResponses 包含多个 @ApiResponse。

3.9 @ApiResponse

@ApiResponse：用在请求的方法上，表示不同的响应。

参数说明：

code = "404"    表示响应码(int型)，可自定义
message = "状态码对应的响应信息"   

@ApiOperation(value = "按照id查找学生信息")
@ApiImplicitParam(name = "id", value = "学生id", dataType = "String", paramType = "path", required = true)
@ApiResponse(code = 200, message = "成功")
@GetMapping("/getStudent/{id}")
public Object getStudent(@PathVariable String id) {
    Student student = studentMapper.selectStudent(id);
    return student;
}

3.10 @ApiIgnore

@ApiIgnore()：用于类或者方法上，不被显示在页面上。

3.11 @Profile

@Profile({“dev”, “test”})：用于配置类上，表示只对开发和测试环境有用。