9、Springboot整合Swagger3

一时失言乱红尘 2023-10-08 17:19 35阅读 0赞

## 1.什么是Swagger？ ##

我们在编写了大量的接口之后，如果接口的调用者不是自身的话，那么就会面临要编写接口文档的苦恼，这时候Swagger就应运而生了。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

### Swagger的组件： ###

*  Swagger spec：这一块对元素的嵌套、命令等采用官方模式。如果你想要对 Swagger 文件手动编码，你必须非常熟悉 Swagger spec。
 *  Swagger editor：这是在线编辑器，用于验证你的 YML 格式的内容是否违反 Swagger spec 。YML 是一种句法，依赖于空格和嵌套。你需要对 YML 句法很熟悉才能很好的遵守 Swagger spec 规范。Swagger 编辑器会标出错误并且给你格式提醒（Swagger spec 文件可以使用 JSON 或者 YAML 中的任意一种格式）。
 *  Swagger-UI：这是一套 HTML/CSS/JS 框架用于解析遵守 Swagger spec 的 JSON 或 YML 文件，并且生成API文档的UI导航。它可以将你的规格文档转换成Swagger Petsotre-like UI。
 *  Swagger-codegen： 这个工具可以为不同的平台生成客户端 SDK（比如 Java、JavaScript、Python 等）。这些客户端代码帮助开发者在一个规范平台中整合 API ，并且提供了更多健壮的实现，可能包含了多尺度、线程，和其他重要的代码。SDK 是用于支持开发者使用 REST API 的工具。
 *  Swagger-validator：这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址，即可校验。

## 2.版本介绍 ##

（1）Spring Boot 版本：2.7.2

（2）Swagger版本：springfox-boot-starter ： 3.0.0

（3）JDK：1.8

## 3.Springboot整合Swagger实例： ##

springfox-boot-starter 该starter包含了一些swagger必要的自动配置类和启动器，其主要包括：

*  springfox-swagger：swagger核心，生成接口文档的Json格式数据
 *  springfox-swagger-ui：swagger可视化，将Json数据可视化展示

### maven配置: ###

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

### yml配置 : ###

spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher

### swagger配置类: ###

package com.springboot.test.config.swagger;
    
    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.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /**
     * @author cf
     * @date 2022/12/3 18:56
     * @description swagger配置类
     */
    @Configuration
    @EnableOpenApi //开启swagger支持
    public class SwaggerConfig {
        
    
        /**
         * Docket类是Swagger的配置类，要自定义修改 Swagger 的默认配置信息，我们需要覆盖该对象
         * @return
         */
        @Bean
        public Docket docket(){
        
            //1.以OAS_30标准构建Docket配置类
            return new Docket(DocumentationType.OAS_30)
                    //2.配置Swagger接口文档基本信息apiInfo
                    .apiInfo(apiInfo())
                    //3.select方法开启配置扫描接口的Builder
                    .select()
                    //4.指定要扫描/维护接口文档的包（否则就全部扫描）
                    .apis(RequestHandlerSelectors.basePackage("com.springboot.test.controller"))
                    //5.路径过滤：该Docket-UI展示时，只展示指定路径下的接口文档(any表示都展示)
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 配置 Swagger 接口文档的基本信息
         * @return
         */
        private ApiInfo apiInfo(){
        
            return new ApiInfoBuilder()
                    //1.接口文档标题
                    .title("SpringBoot整合Swagger")
                    //2.接口文档描述内容
                    .description("这里是SpringBoot整合Swagger的详细信息")
                    //3.项目文档迭代版本
                    .version("9.0")
                    //4.主要联系人信息（姓名name，个人主页url，邮箱email）
                    .contact(new Contact("cf","www.1111.com","1111111@qq.com"))
                    //5.相关许可证信息
                    .license("The CSDN License")
                    //6.相关许可证链接
                    .licenseUrl("www.baidu.com")
                    //7.返回构建的ApiInfo对象
                    .build();
        }
    
    }

### controller进行测试 ###

@GetMapping("mybatisPlus/getUser")
        @ApiOperation(value="Mybatis查询", notes="Mybatis查询")
        public String getMybatisPlusUser() {
        
            TSystemUserMQEntity userEntity = systemUserService.getUserInfo();
            return JSON.toJSONString(userEntity);
        }
    
        @GetMapping("jpa/getUser")
        @ApiOperation(value="JPA查询（已注释）", notes="JPA查询（已注释）")
        public String getJpaUser() {
        
            UserEntity userEntity = userService.getUserInfo();
            return JSON.toJSONString(userEntity);
        }

### 启动 ###

**直接访问：http://localhost:8081/swagger-ui/index.html\#/**  
出来啦 ~~~ 出来啦~~~  
![在这里插入图片描述][354e6de4d9ce47d2961d9cbe6cda1062.png]

## 4.Swagger Api概述 ##

文章只这里使用到了Swagger提供的注解@ApiOperation，常用的注解还有：

（1）@Api：用在类上，说明该类的作用

（2）@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了。

（3）@ApiImplicitParams：用在方法上包含一组参数说明

（4）@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面。

（5）@ApiResponses：用于表示一组响应

（6）@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

（7）@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上

（8）@ApiModelProperty： 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；

[354e6de4d9ce47d2961d9cbe6cda1062.png]: https://img-blog.csdnimg.cn/354e6de4d9ce47d2961d9cbe6cda1062.png