Swagger2的使用-集成至SpringBoot

Swagger2的使用-集成至SpringBoot

前言

作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。

一、简介

官网：https://swagger.io/

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

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

Swagger 的优势

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

二、基本使用

1. 导入相关依赖

通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。

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

2.7之前版本与2.8之后版本 在ui风格上有较大差异

2. 编写配置文件

在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

@EnableSwagger2是springfox提供的一个注解，代表swagger2相关技术开启。会扫描当前类所在包，及子包中所有类型的swagger相关注解，做swagger文档的定制

这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8201/swagger-ui.html#/ （这里我的项目端口是 8201 ，所以我打开的文档地址为 http://localhost:8201/swagger-ui.html# ）即可查看 swagger 文档。

可以看到 Swagger 文档中大概有这四类信息

• 分组信息
• 基本信息
• 接口信息
• 实体类信息

2.1 配置基本信息

Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。

ApiInfo 中默认的基本设置

• title： //接口标题
• description： //接口文档标题说明
• version： //版本
• termsOfServiceUrl： //网站地址
• contact： //Contact类型，包含作者name，网址，邮箱
• license：//协议
• licenseUrl： //协议链接

@Bean
public Docket docket() {
    // 创建一个 swagger 的 bean 实例
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())  // 配置基本信息
            .build();
}

// 基本信息设置
private ApiInfo apiInfo() {
    Contact contact = new Contact(
            "米大傻", // 作者姓名
            "https://blog.csdn.net/xhmico?type=blog", // 作者网址
            "777777777@163.com"); // 作者邮箱
    return new ApiInfoBuilder()
            .title("多加辣-接口文档") // 标题
            .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
            .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
            .version("1.0") // 版本
            .license("Swagger-的使用(详细教程)")
            .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
            .contact(contact)
            .build();
}

2.2配置分组信息

Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default 分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。

@Bean
public Docket docket() {
    // 创建一个 swagger 的 bean 实例
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("***") // 修改组名为 " ***"
            // 配置基本信息
            .apiInfo(apiInfo())
            .select() // 设置扫描接口
            // 配置如何扫描接口
            .apis(RequestHandlerSelectors
                    .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                    //.any() // 扫描全部的接口，默认
                    //.none() // 全部不扫描
                    //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                    //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
            )
            .paths(PathSelectors
                    .any() // 满足条件的路径，该断言总为true
                    //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                    //.ant("/user/**") // 满足字符串表达式路径
                    //.regex("") // 符合正则的路径
            )
            .build();
}

如果需要配置多个组的话，就需要配置多个 docket() 方法，这里我就简单写两组，代码如下：

/**
 * 展示 controller 包下所有的接口
 */
@Bean
public Docket docket1() {
    // 创建一个 swagger 的 bean 实例
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("mike") // 修改组名为 "mike"
            // 配置接口信息
            .select() // 设置扫描接口
            // 配置如何扫描接口
            .apis(RequestHandlerSelectors
                    .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
            )
            .paths(PathSelectors
                     .any() // 满足条件的路径，该断言总为true
            )
            .build();
}

/**
 * 展示路径为 /error 的所有接口（基础接口）
 */
@Bean
public Docket docket2() {
    // 创建一个 swagger 的 bean 实例
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("yank") // 修改组名为 "yank"
            // 配置接口信息
            .select() // 设置扫描接口
            // 配置如何扫描接口
            .apis(RequestHandlerSelectors
                    .any() // 扫描全部的接口，默认
            )
            .paths(PathSelectors
                    .ant("/error") // 满足字符串表达式路径
            )
            .build();
}

3.常见注解、配置接口信息

@ApiModel(POJO类说明)

该注解是作用于类上面的，是用来描述类的一些基本信息的。

• value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
• description：对于类，提供一个详细的描述信息
• parent：这个属性用于描述的是类的一些父类信息
• discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
• subTypes：可以通过这个属性，指定我们想要使用的子类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "Id请求体")
public class IdReq {
    private String id;
}

@ApiModelProperty（POJO类属性说明）

它的作用是添加和操作属性模块的数据。详情：@ApiModelProperty注解的用法

• value: 参数类型为String，作用为此属性的简要描述。
• notes: 参数类型为String，作用为该字段的注释说明。
• example: 参数为String类型，作用为属性的示例值。

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "Id请求体")
public class IdReq {
    @ApiModelProperty("主键id")
    private String id;
}

@Api(接口类说明)

该注解使用在接口Controller上，描述整个Controller的一些信息

• tags： Controller类描述

@Api(tags="订单模块")
@Controller
public class OrderController {
}

@ApiOperation(方法说明)

用在请求的方法上，说明方法的作用

• value:说明方法的作用
• notes:方法的备注说明

@PostMapping(value = "/query-user-info")
@ApiOperation(value = "根据id查询用户详情")
public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) {
    return ResponseBean.success(userService.queryUserInfo(req));
}

@ApiParam(方法参数说明)

• name：参数名
• value：参数说明
• required：是否必填

@PostMapping(value = "/query-user-infos")
@ApiOperation(value = "条件查询用户信息")
public ResponseBean queryUserInfos(
        // name 用户名称 不必填
        @ApiParam(value = "用户名称", required = false) @RequestParam(required = false) String name,
        // gender 用户性别 必填
        @ApiParam(value = "用户性别", required = true) @RequestParam(required = true) GenderEnum gender
) {
    return ResponseBean.success(userService.queryUserInfos(name,gender));
}

三、启动

启动 SpringBoot 应用,访问 http://localhost:8080/swagger-ui.html