Swagger学习笔记

jupiter
2023-08-16 / 0 评论 / 256 阅读 / 正在检测是否收录...
温馨提示:
本文最后更新于2023年09月07日,已超过425天没有更新,若内容或图片失效,请留言反馈。

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界面上的,下面就介绍下常用的注解。

注解方法属性
@Api(tags)标注一个类为 Swagger 资源, 设置资源名称, 默认是类名
@ApiOperation(value) 标注一个请求, 设置该请求的名称, 默认是方法名
@ApiParam (不常用) 仅用于 JAX-RS
@ApiImplicitParam (常用) 功能同 @ApiParame, 可用于 Servlet
@ApiImplicitParams 包裹多个参数描述注解
@ApiModel标注一个实体类
@ApiModelProperty 标注实体属性, 设置属性的备注信息
@ApiResponse 描述响应码,以及备注信息
@ApiResponses 包裹多个响应描述注解
@ApiIgnore使swagger忽略某个资源使swagger忽略某个接口使swagger忽略某个属性

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.)

对应关系为:

swagger2OpenAPI 3注解位置
@Api@Tag(name = “接口类描述”)Controller 类上
@ApiOperation@Operation(summary =“接口方法描述”)Controller 方法上
@ApiImplicitParams@ParametersController 方法上
@ApiImplicitParam@Parameter(description=“参数描述”)Controller 方法上 @Parameters
@ApiParam@Parameter(description=“参数描述”)Controller 方法的参数上
@ApiIgnore@Parameter(hidden = true)@Operation(hidden = true)@Hidden-
@ApiModel@SchemaDTO类上
@ApiModelProperty@SchemaDTO属性上

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 {
}

备注:这里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相关的相关注解

注解说明
@Configuration用于SwaggerConfig类前表明这是个配置类,项目会自动把Swagger页面加载进来
@EnableSwagger2开启Swagger页面的使用
@Bean用于返回Docket的方法前,Docket持有对各个接口的具体处理。

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博客
0

评论 (0)

打卡
取消