Swagger学习笔记

1.简介

1.1 产生背景

故事还是要从前后端分离讲起啊

• 前后端分离：VUE+SpringBoot 基本上都用这一套
• 后端时代：前端只用管理静态页面，html===》后端，使用模版引擎 jsp=》后端主力

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层【后端团队】
• 前端：前端控制层，视图层，【前端团队】
• 伪造后端数据，json，已经存在数据，不需要后端，前端工程依旧可以跑起来
• 前后端如何交互 ====》API
• 前后端相对独立，松耦合
• 前后端甚至可以部署在不同的服务器上

产生一个问题：

• 前后端联调，前端和后端人员无法做到及时协商，解决问题，导致问题爆发
• 需要一个东西可以解决这个问题

解决问题：

• 首先指定计划，实时更新API，较低集成风险
• 早些年：指定word计划文档

1.2 Swagger介绍

Swagger是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档。Swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）

2.Swagger注解

2.1 常用注解-swagger2版本

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

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

参数：

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

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

参数：

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

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

参数：

description="描述实体的作用"  

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

参数：

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

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

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

参数：

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

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

参数：

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

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

一个@ApiResponses包含多个@ApiResponse

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

参数：

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

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

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

2.2 使用 swagger3 注解代替 swagger2 的（可选）

这一步是可选的，因为改动太大，故 springfox对旧版的 swagger做了兼容处理。
但不知道未来会不会不兼容，这里列出如何用 swagger 3 的注解（已经在上面引入）代替 swagger 2 的
(注意修改 swagger 3 注解的包路径为io.swagger.v3.oas.annotations.)

对应关系为：

Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。

3.SpringBoot集成Swagger2

3.1 pom.xml依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

3.2 简单集成

• 简单编写一个controller

@RestController
@RequestMapping("/")
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello springboot!";
    }
}

• 编写 Swagger 配置类，默认什么都不写会扫描所有

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
}

• 访问接口文档:http://localhost:8080/swagger-ui.html

备注：这里springboot3会不支持(版本太高)，改为了2.6.1，否则运行会报如下错误，

org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'apiDocumentationScanner' defined in URL [jar:file:/C:/Users/LuoJia/.m2/repository/io/springfox/springfox-spring-web/2.9.2/springfox-spring-web-2.9.2.jar!/springfox/documentation/spring/web/scanners/ApiDocumentationScanner.class]: Unsatisfied dependency expressed through constructor parameter 1: Error creating bean with name 'apiListingScanner' defined in URL [jar:file:/C:/Users/LuoJia/.m2/repository/io/springfox/springfox-spring-web/2.9.2/springfox-spring-web-2.9.2.jar!/springfox/documentation/spring/web/scanners/ApiListingScanner.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'apiDescriptionReader' defined in URL [jar:file:/C:/Users/LuoJia/.m2/repository/io/springfox/springfox-spring-web/2.9.2/springfox-spring-web-2.9.2.jar!/springfox/documentation/spring/web/scanners/ApiDescriptionReader.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'cachingOperationReader' defined in URL [jar:file:/C:/Users/LuoJia/.m2/repository/io/springfox/springfox-spring-web/2.9.2/springfox-spring-web-2.9.2.jar!/springfox/documentation/spring/web/scanners/CachingOperationReader.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'apiOperationReader' defined in URL [jar:file:/C:/Users/LuoJia/.m2/repository/io/springfox/springfox-spring-web/2.9.2/springfox-spring-web-2.9.2.jar!/springfox/documentation/spring/web/readers/operation/ApiOperationReader.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'documentationPluginsManager': Unsatisfied dependency expressed through field 'documentationPlugins': Error creating bean with name 'documentationPluginRegistry': FactoryBean threw exception on object creation
    at org.springframework.beans.factory.support.ConstructorResolver.createArgumentArray(ConstructorResolver.java:800) ~[spring-beans-6.0.11.jar:6.0.11]
    at org.springframework.beans.factory.support.ConstructorResolver.autowireConstructor(ConstructorResolver.java:245) ~[spring-beans-6.0.11.jar:6.0.11]
    ···

3.3 高级集成

3.3.1 相关注解

SwaggerConfig相关的相关注解

3.3.2 配置基本信息和swagger扫描范围

新建config包，创建SwaggerConfig类，重点注意基于.apis和.paths配置swagger扫描范围的配置。

package com.example.testspringboot.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagge2Config {
    // 配置swagger页面的头部 即api文档的详细信息介绍
    private ApiInfo setApiInfo() {
        return new ApiInfoBuilder()
                .title("XX平台API接口文档") //页面标题
                .contact(new Contact("jupiter", "https://blog.inat.top",
                        "xxxxxx@qq.com"))//联系人
                .version("1.0")//版本号
                .description("系统API描述")//描述
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定swagger2版本
                .enable(true)   // 开关
                .apiInfo(setApiInfo())// 配置swagger页面的头部信息
                .select()// 配置扫描接口，使用过滤，必须先调用select方法；
                /**
                 * 通过apis方法，basePackage可以根据包路径来生成特定类的API，
                 * any() // 扫描所有，项目中的所有接口都会被扫描到
                 * none() // 不扫描接口
                 * withMethodAnnotation(final Class<? extends Annotation> annotation)
                 * 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                 *  withClassAnnotation(final Class<? extends Annotation> annotation)
                 *  通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                 *  basePackage(final String basePackage) // 根据包路径扫描接口
                 */
                .apis(RequestHandlerSelectors.basePackage("com.example.testspringboot.controller"))
                /**
                 *除此之外，我们还可以通过.paths方法配置接口扫描过滤
                 * any() // 任何请求都扫描
                 * none() // 任何请求都不扫描
                 * regex(final String pathRegex) // 通过正则表达式控制
                 * ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.any())
                .build(); // 使用了select()方法后必须进行build
    }

}

3.3.3 swagger分组

• 如果项目大了之后可能有几百上千个接口。如果全在一个组内，找起来特别麻烦。
• swagger可以配置多个Docket，每个Docket都可以设置一个分组，并设定每个Docket的单独过滤规则。
• 这样就完美设置成了一个大的功能模块对应一个分组。
• 可以通过.groupName方法设置分组名。

  @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("group1")
                .enable(swaggerModel.isEnable())
                .select()
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("group2")
                .enable(swaggerModel.isEnable())
                .select()
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("group3")
                .enable(swaggerModel.isEnable())
                .select()
                .paths(PathSelectors.any())
                .build();
    }

3.3.4 Swagger换皮肤

皮肤的使用非常简单，只需简单的引入依赖即可。

• bootstrap-ui

 <!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

• swagger-mg-ui

<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

• knife4j

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>2.0.6</version>
</dependency>

4.SpringBoot集成Swagger3

4.1 配置文件

• pom.xml

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

• application.yml

springdoc:
    swagger-ui:
        path: /swagger-ui.html
        tags-sorter: alpha
        operations-sorter: alpha
        enabled: true
    api-docs:
        path: /v3/api-docs
        enabled: true
    group-configs:
          group: platform
          paths-to-match: /**
          packages-to-scan: com.license4j.license
 
knife4j:
    enable: true
    setting:
        language: zh_cn

然后，就可以启动测试输入地址http://ip:port/doc.html

参考资料

1. API Documentation & Design Tools for Teams | Swagger
2. swagger：快速入门_冷环渊的博客-CSDN博客
3. Swagger3学习笔记_swagger3 @apiresponses_C.kai的博客-CSDN博客
4. Swagger3 学习笔记 - xtyuns - 博客园 (cnblogs.com)
5. Swagger笔记—Swagger3详细配置-腾讯云开发者社区-腾讯云 (tencent.com)
6. 齐全的swagger注解介绍 - 知乎 (zhihu.com)
7. Swagger与Docket - ShineLe - 博客园 (cnblogs.com)
8. SpringBoot集成swagger2报错‘apiDocumentationScanner‘ defined in URL_吃啥？的博客-CSDN博客
9. swagger配置扫描接口、扫描路径条件_swagger docket该路径_呐呐呐-的博客-CSDN博客
10. SpringBoot集成Swagger（六）玩转groupName()分组 | Java随笔记 - 掘金 (juejin.cn)
11. springBoo3.0集成knife4j4.1.0（swagger3）_华义辰的博客-CSDN博客
12. Springboot3.0.0+集成SpringDoc并配置knife4j的UI_Anakki的博客-CSDN博客