Swagger2&Swagger3

男娘i 2023-10-11 20:35 10阅读 0赞

## 一、什么是Swagger ##

swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。

所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有： word(相当于没说)， YAPI, 小幺鸡等，这种文档需要程序员在上面编写，也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息，然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时，需要回过头来维护上面的内容，很麻烦，是真的麻烦。

实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，主需要按时发布即可。但是由于是根据代码自动生成的，所以最大的弊端就是代码侵入性强，需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多，但是swagger还是其中比较有影响力的一个。

## 二、[SpringBoot集成swagger][SpringBoot_swagger]2 ##

官网地址： [swagger.io][] 当然，官网都是英文的，看起来还是比较麻烦的。建议大家直接按照我的步骤来，还是很简单的。

同时在说一点： swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大，主要对于依赖和注解进行了优化。swagger2需要引入2个jar包，swagger3只需要一个，用起来没有什么大的区别。下面以swagger2为例。

### 第1步：pom.xml中添加Swagger2的坐标 ###

<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步：添加Swagger的配置文件 ###

首先需要添加一个注解 ： @EnableSwagger2。 这个注解我们可以添加到SpringBoot的启动类上，也可以自定义一个配置类，放到上面。添加了这个注解以后，就代表我们已经在项目中开启了Swagger的功能。

我们采用第二种方式，自己定义一个配置类，正好还可以添加一个Docket配置（Swagger API 摘要对象）。 所谓Docket配置，就是一组(一个项目或一个版本)接口文档的配置，比如设置名称， 联系人等等。

我们在config文件夹下，添加一个SwaggerConfig类。

在 SwaggerConfig 中添加两个方法：（其中一个方法是为另一个方法作辅助的准备工作）  
api()方法使用 **@Bean**，在启动时初始化，返回实例 Docket（Swagger API 摘要对象），这里需要注意的是 `.apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz"))` 指定需要扫描的包路路径，只有此路径下的 Controller 类才会自动生成 Swagger API 文档。

package demo.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /**
     * Swagger配置类
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    // 此处自行修改为自己的 Controller 包路径。
                    .apis(RequestHandlerSelectors.basePackage("demo.controller")).paths(PathSelectors.any())
                    .build().globalOperationParameters(setHeaderToken());
    
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("XXX 项目接口文挡")
                    .description("swagger实战")  //说明信息
                    .termsOfServiceUrl("") //文档生成的主页地址
                    .version("1.0").build(); //文档版本
        }
    
        private List<Parameter> setHeaderToken() {
            List<Parameter> pars = new ArrayList<>();
            ParameterBuilder userId = new ParameterBuilder();
            userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                    .required(true).build();
            pars.add(userId.build());
            return pars;
        }
    }

上面就是一个配置案例， 还设置了一个setToken方法，代表生成文档的所有接口中，都要包含一个header类型的token参数。

### 第3步：给Controller添加Swagger注解 ###

我们接口文档的直接描述主要就是在Controller这一层，比如这个接口的功能，参数的名称，返回值的名称等。这些值我们都需要在Controller上通过给方法上，请求参数和返回参数上添加对应的注解，swagger才能帮我们生成相应的接口文档。这也就是我前面提到的对现有代码的侵入性。

### 2.1、案例 ###

首先先创建一个vo的包，里边写我们的请求和相应参数，使用JavaBean定义出请求和响应的数据结构。注意这里要添加相应的注解

#### 请求参数类UserVO实体 ####

package demo.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel("创建User请求参数")
    public class UserVO {
    
        @ApiModelProperty("id")
        private Integer id;
    
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("性别")
        private Integer gender;
    }

#### 请求响应类User实体 ####

package demo.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel("创建User响应结果")
    public class User {
    
        @ApiModelProperty("id")
        private Integer id;
    
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("性别")
        private Integer gender;
    
        @ApiModelProperty("住址")
        private String addr;
    }

#### TestController ####

package demo.controller;
    
    import demo.entity.UserVO;
    import demo.entity.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.*;
    
    @RestController
    @RequestMapping("/swagger")
    @Api(value = "用户接口", tags = {"用户接口"}) //定义接口的组名
    public class TestController {
    
        @ApiOperation("新增用户") //定义接口的名称
        @PostMapping("save")
        public String save(@RequestBody UserVO req) {
            return "success";
        }
    
        @ApiOperation("根据条件查询用户") //定义接口的名称
        @GetMapping("getById")
        public User getById(@RequestBody User req) {
            return new User();
        }
    }

#### 启动项目 ####

当启动项目的时候，我们发现会出现错误，异常原因是：SpringBoot2.6版本和Swagger2.9.2不兼容导致的。，也有人说是由于guava这个包的版本过低导致的，所以最简单的解决办法是将SpringBoot的版本改到2.6以下。当然，如果项目中的SpringBoot版本不能修改的话，我们还可以在application.yml配置文件中进行修改。![c7f00480de1b4f39b15f5ff543afc55b.png][]

**修改application.yml配置文件**  
PathPatternMatcher匹配路径，Swagger引用的Springfox使用的路径匹配是基于AntPathMatcher的。  
所以要想解决，添加配置，将springBoot MVC的路劲匹配模式修改一下即可。

application.yml

spring:
      mvc:
        pathmatch:
          matching-strategy: ANT_PATH_MATCHER

再次重启项目，问题解决。

#### 测试访问 ####

访问地址： ip:端口号/swagger-ui.html![25eb8e85899e4e14aa04d897c4bc0341.png][]

正常情况就可以看到我们的界面了。一会再说非正常情况。由于我们只给用户接口添加了注解，所有用户接口是可以直接观察中文文档的。而剩下的两个接口，由于没添加注解，所以都是以默认的形式展示的。

点开接口，我们可以看到接口中的想详细信息![18260ed8e87e4c27a546af2fc8438da3.png][]

点击model,可以看到字段的中文描述。点击 Try it out,就可以直接调试接口。同时注意接口中都让填一个token,这就是我们之前的设置成效了。![2888e75942144db79b272c966a3806a4.png][]

截止到目前其实swagger的集成就已经完毕了，主要就是根据我们的注解生成文档，并且可以在线调用调试。开发的时候，我们只需要把Controller这一层的请求和响应，以及方法描述等内容先开发完毕，就可以提供给前端让他们参照开发了。

### 2.2、 \[404\]问题解决 ###

正常情况我们按照上面的步骤就可以出现页面，但是有些时候可能是由于springBoot的版本过高导致的，我们输入之前的地址，出现404的情况，这个主要是由于项目中无法读取到swagger依赖包下的页面导致的。如果出现了这个问题，我们可以添加一个配置类，让他实现WebMvcConfigurer 接口，在添加一个方法

package demo.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    
    @Configuration
    public class WebMvcConfig implements WebMvcConfigurer {
        
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

这个时候在启动就可以了！

### 2.3、替换UI ###

上面的整个过程已经完成了，但是生成的接口文档的页面，其实很多人不太喜欢，觉得不太符合国人的使用习惯，所有又有一些大神，提供了其他的UI测试页面。这个页面的使用还是比较广泛的。

修改方式：只需引入一个依赖包：

<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.9.6</version>
            </dependency>

然后把刚才实现的那个的那个方法再添加一条：

registry.addResourceHandler("doc.html")
                    .addResourceLocations("classpath:/META-INF/resources/");

重新启动项目： 访问路径发生了变化：\*\* ip:端口号/doc.html\*\*

![b8ecca79e24b4a04985700d45a48c0a8.png][] 页面出现了。我们在看看我们的用户接口：![50ed5020101749dea599e24c30fc2b01.png][]

这个风格确实更加的直观，同时也是可以直接进行调试的。大部分的swagger都用的这个风格的文档。

### 2.4、源代码 ###

[swagger2-demo.zip][]

## 三、SpringBoot集成swagger3 ##

上面已经很详细的讲解了swagger2的集成方式，而swagger3的集成方式更加的简洁一些。

### 第1步：pom.xml中添加Swagger3的坐标 ###

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

### 第2步：Swagger配置类 ###

然后是替换注解： swagger2使用的开启注解是： @EnableSwagger2  
而在swagger3中，这个注解要换成： @EnableOpenApi

package demo.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /**
     * Swagger配置类
     */
    @Configuration
    @EnableOpenApi // v2 不同
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30) // v2 不同
                    .apiInfo(apiInfo()).select()
                    // 此处自行修改为自己的 Controller 包路径。
                    .apis(RequestHandlerSelectors.basePackage("demo.controller")).paths(PathSelectors.any())
                    .build().globalOperationParameters(setHeaderToken());
    
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("XXX 项目接口文挡")
                    .description("swagger实战")  //说明信息
                    .termsOfServiceUrl("") //文档生成的主页地址
                    .version("1.0").build(); //文档版本
        }
    
        private List<Parameter> setHeaderToken() {
            List<Parameter> pars = new ArrayList<>();
            ParameterBuilder userId = new ParameterBuilder();
            userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                    .required(true).build();
            pars.add(userId.build());
            return pars;
        }
    }

要注意，里边的版本类型换成了 OAS\_30, 就是swagger3的意思。

> **Tips**：OAS 是 OpenAPI Specification 的简称，翻译成中文就是 OpenAPI 说明书。

同时访问地址：原始地址，也就是没换UI的地址： localhost:8080/swagger-ui/index.html这个要和swagger2区分开。  
swagger3的原始UI风格也发生了一些变化：![bd6168849b224b9a8617f8cb8e33e581.png][]

同时swagger3也是可以更换UI的。方法和swagger2一样。![b4ba182d1d4c4c42994d0e59ed36761e.png][]

### 源代码 ###

[swagger3-demo.zip][]

## 扩展：swaggerUI 拦截器和跨域冲突处理 ##

如果我们的项目中有关于跨域的处理，同时还有拦截器，然后还要使用swagger，这种情况大家要注意了，有可能我们的拦截器会将swagger中的页面路径拦截掉导致swagger页面出不来，当我们在拦截器中把swagger的页面排除掉的时候，也有可能会导致跨域配置的失效。

详细的解决方案可以看我之前写过的一篇博客： [springboot跨域过滤器与swagger拦截器冲突的解决方案][springboot_swagger]  
具体解决方案简单提一下：

### 第1步：定义拦截器 ###

/**
     * 拦截器配置
     *
     */
    @Configuration
    public class InterceptorConfig implements WebMvcConfigurer {
     
        @Bean
        public TokenInterceptor tokenInterceptor() {
            return new TokenInterceptor();
        }
     
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            registry
                    .addInterceptor(tokenInterceptor())
                    .addPathPatterns("/**")
                    .excludePathPatterns("/user/login")
                    .excludePathPatterns("/user/downloadExcel")
                    .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
        }
     
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

### 第2步：跨域配置 ###

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.cors.CorsConfiguration;
    import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
    import org.springframework.web.filter.CorsFilter;
     
    @Configuration
    public class CorsConfig {
     
        @Bean
        public CorsFilter corsFilter() {
            CorsConfiguration config = new CorsConfiguration();
            config.addAllowedOrigin("*");
            config.setAllowCredentials(true);
            config.addAllowedMethod("*");
            config.addAllowedHeader("*");
            UrlBasedCorsConfigurationSource configSource = new UrlBasedCorsConfigurationSource();
            configSource.registerCorsConfiguration("/**", config);
            return new CorsFilter(configSource);
        }
    }

用这两种方式去配置，就可以让他们和平共处了。

[SpringBoot_swagger]: https://so.csdn.net/so/search?q=SpringBoot%E9%9B%86%E6%88%90swagger&spm=1001.2101.3001.7020
[swagger.io]: https://swagger.io/
[c7f00480de1b4f39b15f5ff543afc55b.png]: https://img-blog.csdnimg.cn/c7f00480de1b4f39b15f5ff543afc55b.png
[25eb8e85899e4e14aa04d897c4bc0341.png]: https://img-blog.csdnimg.cn/25eb8e85899e4e14aa04d897c4bc0341.png
[18260ed8e87e4c27a546af2fc8438da3.png]: https://img-blog.csdnimg.cn/18260ed8e87e4c27a546af2fc8438da3.png
[2888e75942144db79b272c966a3806a4.png]: https://img-blog.csdnimg.cn/2888e75942144db79b272c966a3806a4.png
[b8ecca79e24b4a04985700d45a48c0a8.png]: https://img-blog.csdnimg.cn/b8ecca79e24b4a04985700d45a48c0a8.png
[50ed5020101749dea599e24c30fc2b01.png]: https://img-blog.csdnimg.cn/50ed5020101749dea599e24c30fc2b01.png
[swagger2-demo.zip]: https://download.csdn.net/download/qzc70919700/87362462
[bd6168849b224b9a8617f8cb8e33e581.png]: https://img-blog.csdnimg.cn/bd6168849b224b9a8617f8cb8e33e581.png
[b4ba182d1d4c4c42994d0e59ed36761e.png]: https://img-blog.csdnimg.cn/b4ba182d1d4c4c42994d0e59ed36761e.png
[swagger3-demo.zip]: https://download.csdn.net/download/qzc70919700/87362500
[springboot_swagger]: https://lsqingfeng.blog.csdn.net/article/details/110480709?spm=1001.2014.3001.5502