【Swagger】配置信息详解（涉及源码分析）

￡神魔★判官ぃ 2022-10-24 13:11 306阅读 0赞

先来说说 Swagger 有什么用，相较于使用 markdown 或者 word 写接口文档，Swagger 自动生成 API 文档，然后在 web 端暴露，并且 API 文档与 API 定义同步更新，这解决了前后端交互时接口更改但协商不及时的问题。另外，Swagger 还内置了在线测试功能，使得开发与接口测试一条龙，因此 Swagger 现在被很多公司使用。

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>

> 注意：本篇是基于 SpringBoot 来构建
> 
> 1.  Swagger 是在 web 端显示，所以还需要引入 starter-web
> 2.  Swagger2 要求 JDK 版本至少是 1.8，否则无法运行

使用 Swagger 总的分为两步：

1.  写配置类
2.  使用注解

本篇我们就来看看如何编写配置类，关于有哪些注解请看[下一篇][Link 1]…

### 创建配置类，启动 Swagger ###

Swagger 的实例 Bean 是 Docket，所以通过配置 Docket 实例来配置 Swaggger。

下面，我们新建一个 SwaggerConfig：

@Configuration
    @EnableSwagger2 // 启动 Swagger2
    public class SwaggerConfig {
        
        
        @Bean // 构建并配置 Docket 对象
        public Docket docket() {
        
        }
    }

至此，我们其实已经能将 Swagger 启动起来了。启动 SpringBoot 项目，浏览器输入 [http://localhost:8080/swagger-ui.htm][http_localhost_8080_swagger-ui.htm]，就可以看到它的界面：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center]

但里面的东西显然不是我们想要的，我们需要根据实际情况进行配置，比如接口文档名称，作者信息等。那我们该怎么配置 Docket 对象呢？

### 1.Docket 源码分析 ###

打开 Docket 的源码，我们可以看见 Docket 提供了很多可以配置的属性，并且提供了相应的 setter（注：方法与属性名同名，返回值是 this(链式编程)）

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 1]

可以看到，它设置默认的分组 DEFAULT\_GROUP\_NAME 是 default，没错，这就和右上角的 spec 对应上了：

![在这里插入图片描述][20210129163631563.png_pic_center]

另外，还有很多我们可以自行配置的属性，下面我们来就来看看其中比较重要的几个…

### 2.DocumentationType 文档类型 ###

可以看到 Docket 的构造函数需要一个 DocumentationType 作为参数，我们点进它的源码看看：

![在这里插入图片描述][20210129163852927.png_pic_center]

可以看到，它提供了三个构造好的 DocumentationType 常量，设置了使用 Swagger 哪个版本。

我们现在一般使用的是 Swagger2，所以在构造 Docket 对象时传入 DocumentationType.SWAGGER\_2：

### 3.ApiInfo 基本信息 ###

ApiInfo 见名知意，提供了一些基本信息的配置，这些配置信息可以显示 UI 界面上。同样的，点进它的源码看看

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 2]  
可以看到，它提供了 8 个可以配置属性，根据名字也能猜出其中的意思。

*  version：API 版本
 *  title：文档标题
 *  description：文档描述
 *  termsOfServiceUrl：团队链接
 *  license：许可
 *  licenseUrl：许可链接
 *  contact：联系人信息
 *  vendorExtensions：扩展信息

这里注意，在 ApiInfo 中还有一个默认配置 DEFAULT，它看起来是不是很熟悉？没错，它就是我们在不做任何配置下启动 Swagger 显示的基本信息

![在这里插入图片描述][20210129163739875.png_pic_center]

现在我们来配置自己的 ApiInfo

> 注：ApiInfo 中没有提供 setter，所以我们可以通过 ApiInfo 的构造函数去构建，也可以通过 ApiInfoBuilder 去逐项赋值。

@Configuration
    @EnableSwagger2 // 启动 Swagger2
    public class SwaggerConfig {
        
        
        @Bean // 构建并配置 Docket 对象
        public Docket docket() {
        
            return new Docket(DocumentationType.SWAGGER_2);
        }
        
        // 构建基本配置信息
        public ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("文档标题")
                    .description("测试的接口文档")
                    .version("v2.0")
                    .termsOfServiceUrl("baidu.com")
                    .contact(new Contact("A minor", "https://blog.csdn.net/weixin_43935927", "3132266573@qq.com"))
                    .build();
        }
    }

然后重启 SpringBoot 项目  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 3]

### 4.ApiSelectorBuilder 扫描接口 ###

构建 Docket 时通过 select() 方法配置怎么扫描接口，它会返回一个 ApiSelectorBuilder 对象

![在这里插入图片描述][20210129163910966.png_pic_center]

点开 ApiSelectorBuilder 源码：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 4]

可以看到，它需要配置的是 requestHandlerSelector 和 pathSelector。

**1）requestHandlerSelector**

接口扫描方案。通过 ApiSelectorBuilder\#apis() 方法配置（也是链式编程），在 RequestHandlerSelectors 提供了配置方案：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 5]

*  any()：扫描所有，项目中的所有接口都会被扫描到
 *  none()：不扫描接口
 *  withClassAnnotation()：扫描注解
 *  withMethodAnnotation()：扫描方法上的注解，比如 withMethodAnnotation(GetMapping.class) 只扫描 @GetMapping 标识的 GET 请求
 *  withClassAnnotation()：扫描类上的注解，比如 withClassAnnotation(Controller.class) 只扫描有 @Controller 注解的类中的接口
 *  basePackage()：扫描指定路径，比如 basePackage(“com.test.controller”) 只扫描 controller 包的解耦

> PS：常用的是 basePackage()，只去扫描 controller 包。

**2）pathSelector**

接口过滤方案。

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解（见[下一篇][Link 1]）另一种是在 Docket 上增加筛选。两种方式的区别是，Docket 配置的规则，可以对多个接口器过滤作用，而 @ApiIgnore 只能作用于单个接口。

本篇我们先来看第二种，这种方式可以通过筛选 API 的 url 来进行过滤；通过 ApiSelectorBuilder\#paths() 方法配置，在 PathSelectors 提供了配置方案：

![在这里插入图片描述][20210129163955580.png_pic_center]

*  any()：任何路径都满足条件
 *  none()：任何路径都不满足条件
 *  regex()：通过正则表达式控制
 *  ant()：通过 ant 控制

> PS：常用的是 any()，不做特殊处理。

在 ApiSelectorBuilder 中提供了默认配置方案 DEFAULT，即不扫描所有标有 @ApiIgnore 注解的类和方法，允许所有的请求路径：

![在这里插入图片描述][20210129164013144.png_pic_center]

所以，在一开始，我们才会看到 [basic-error-controller][] 中的这些我们自己没配置过的接口

![在这里插入图片描述][20210129164025349.png_pic_center]

好了，现在我们来看一下在 SwaggerConfig 中该怎样配置：

@Bean
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select() // 返回 ApiSelectorBuilder 
                    .apis(RequestHandlerSelectors.basePackage("com.test.controller")) // 接口扫描方案
                    .paths(PathSelectors.any()) // 接口过滤方案
                    .build();
    }

在 controller 包新建一个 TestController，然后重启项目后就能看到我们自己的接口了，并且 basic-error-controller 也没了。

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 6]

### 5.groupName 分组 ###

groupName 就是上面说的右上角的分组选项，一般项目中不同的开发人员，可以创建不同的分组，默认的分组是 default。所以，我们可以通过配置多个 Docket 去实现分组

@Bean // 构建并配置 Docket 对象
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 返回 ApiSelectorBuilder
                .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
                .paths(PathSelectors.any()) // 接口过滤方案
                .build();
    
    }
    
    @Bean
    public Docket docket2() {
        
        return new Docket(DocumentationType.SWAGGER_2).groupName("打工人2组");
    }
    
    @Bean
    public Docket docket3() {
        
        return new Docket(DocumentationType.SWAGGER_2).groupName("打工人3组");
    }

![在这里插入图片描述][20210129164048668.png_pic_center]

### 6.useDefaultResponseMessages 默认状态码 ###

点开接口文档中的接口，可以看见，在 Respon 中 Swagger 默认提供了 200,401,403,404 这几个状态码

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 7]

但是，在我们实际开发中，大多数都是自定义状态码的；所以，就可以通过 useDefaultResponseMessages(false) 关闭默认状态码。配置如下：

@Bean // 构建并配置 Docket 对象
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select() // 返回 ApiSelectorBuilder
                .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
                .paths(PathSelectors.any()) // 接口过滤方案
                .build();
    
    }

重启项目后，可以看到，原先的 401,403,404 没有了

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 8]

### 7.enabled 是否启动 Swagger ###

我们在开发、测试时候需要启动 Swagger，但是在实际项目发布上线了就要关闭它，因为一旦一些重要的接口暴露是很危险的，而且一直运行着 Swagger 也会浪费系统资源。

所以可以通过 Docket\#enable(false) 来关闭 Swagger，但是如果每次都手动操作显得有些笨拙，我们可以根据当前项目的环境来决定是否开启 Swagger。

1）创建两个新的配置文件，application-dev…properties 和 application-por…properties，分别代表正式环境和开发环境的配置。在这两个配置文件中，分别把启动端口设为 8081 和 8080

![在这里插入图片描述][20210129225447165.png_pic_center]

2）修改 SwaggerCofing，让它根据环境开启 Swagger

3）修改 application.properties，将当前环境置为 dev

![在这里插入图片描述][20210129225421860.png_pic_center]

然后重启项目，就可以发现，8080 端口已经无法访问了，但8081 可以。

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 9]

> Docket 其余的配置信息我在这里不说了，有用到或者想了解的同学可以自行查阅官网文档。

### 完整代码 ###

@Configuration
    @EnableSwagger2 // 启动 Swagger2
    public class SwaggerConfig {
        
        
        @Bean // 构建并配置 Docket 对象
        // 注：这里注入了 Environment 对象，目的是获取系统环境
        public Docket docket(Environment environment) {
        
    
            // 设置要显示 swagger 的环境（dev 或者 test）
            Profiles of = Profiles.of("dev", "test");
            // 判断当前是否处于该环境
            boolean flag = environment.acceptsProfiles(of);
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(flag)
                    .useDefaultResponseMessages(false)
                    .select() // 返回 ApiSelectorBuilder
                    .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
                    .paths(PathSelectors.any()) // 接口路径过滤方案
                    .build();
    
        }
    
        // 构建基本配置信息
        public ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("文档标题")
                    .description("测试的接口文档")
                    .version("v2.0")
                    .termsOfServiceUrl("baidu.com")
                    .contact(new Contact("A minor", "https://blog.csdn.net/weixin_43935927", "3132266573@qq.com"))
                    .build();
        }
    
        @Bean
        public Docket docket2() {
        
            return new Docket(DocumentationType.SWAGGER_2).groupName("打工人2组");
        }
    
        @Bean
        public Docket docket3() {
        
            return new Docket(DocumentationType.SWAGGER_2).groupName("打工人3组");
        }
    }

> 关于 Swagger 中的注解在[下一篇][Link 1]文章，包括注解的完整代码我放到 GitHub 上了，点击[这里][Link 2]跳转…

[Link 1]: https://blog.csdn.net/weixin_43935927/article/details/113401678
[http_localhost_8080_swagger-ui.htm]: http://localhost:8080/swagger-ui.htm
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center]: /images/20221024/341c86e725d64a7a850c9d162d3a7e1e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221024/894e6ba370234537bf47784f43cdf2a1.png
[20210129163631563.png_pic_center]: /images/20221024/d3fc360478ab41d0bc9accdf27fce937.png
[20210129163852927.png_pic_center]: /images/20221024/846a92b245a64c5f91a5f832c3029d17.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221024/55a1b4139cdd4a61952e6614b48f9860.png
[20210129163739875.png_pic_center]: /images/20221024/86b34a6f8bb04e7fa7afd8b0a5917511.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20221024/03710146b3924775ad143e80ab5e83f4.png
[20210129163910966.png_pic_center]: /images/20221024/49c0cd49f22c4a3fab709f2b2284ed2a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 4]: /images/20221024/1ad4a0128b3446ed808aff56aa46f251.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 5]: /images/20221024/9df9908cb68142cd945a3b9c067dfaee.png
[20210129163955580.png_pic_center]: /images/20221024/6b3c87b65dba49dca811d38bcf14b9d6.png
[20210129164013144.png_pic_center]: /images/20221024/f131147fe49d4f3d942cec609e538cc5.png
[basic-error-controller]: http://localhost:8080/swagger-ui.html#/basic-error-controller
[20210129164025349.png_pic_center]: /images/20221024/e1c10f2659514e4a907b5ec6ba8e6f4f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 6]: /images/20221024/9249774cb97149db8b2dcbecc860a29d.png
[20210129164048668.png_pic_center]: /images/20221024/9999148d8ea043e48d90d99d68df4293.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 7]: /images/20221024/1be847a6934246e5abdf8db5befa9432.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 8]: /images/20221024/04b265db786f420b8a9d70c5bdf36e30.png
[20210129225447165.png_pic_center]: /images/20221024/035bccba2dd048adbff34ef6ec0b131b.png
[20210129225421860.png_pic_center]: /images/20221024/b8e03205715345a1b67898374c778894.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzkzNTkyNw_size_16_color_FFFFFF_t_70_pic_center 9]: /images/20221024/87680d168318467cbdab6be01c21ba17.png
[Link 2]: https://github.com/YZHyaa/others/tree/main/swagger