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

向右看齐 2022-11-08 14:24 180阅读 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]，就可以看到它的界面：

![在这里插入图片描述][20210129163554753.png]

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

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

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

![在这里插入图片描述][20210129163616372.png]

可以看到，它设置默认的分组 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 界面上。同样的，点进它的源码看看

![在这里插入图片描述][20210129163709127.png]  
可以看到，它提供了 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 项目  
![在这里插入图片描述][20210129163754794.png]

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

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

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

点开 ApiSelectorBuilder 源码：  
![在这里插入图片描述][20210129164304490.png]

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

**1）requestHandlerSelector**

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

![在这里插入图片描述][20210129163942734.png]

*  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 也没了。

![在这里插入图片描述][20210129164036364.png]

### 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 这几个状态码

![在这里插入图片描述][20210129164100750.png]

但是，在我们实际开发中，大多数都是自定义状态码的；所以，就可以通过 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 没有了

![在这里插入图片描述][20210129164110550.png]

### 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 可以。

![在这里插入图片描述][20210129225432117.png]

> 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组");
        }
    }

[Link 1]: https://blog.csdn.net/weixin_43935927/article/details/113401678
[http_localhost_8080_swagger-ui.htm]: http://localhost:8080/swagger-ui.htm
[20210129163554753.png]: /images/20221023/1dbbd9f01a304086ad41f8e05f3ea1f4.png?
[20210129163616372.png]: /images/20221023/33f1cd12e81a459f904f6e665bfc1601.png?
[20210129163631563.png_pic_center]: /images/20221023/7513e554df6a4693bce9fdd716684096.png
[20210129163852927.png_pic_center]: /images/20221023/f3f9fb04cd7d432ab4e319f5d542ec99.png
[20210129163709127.png]: /images/20221023/60cfa75edbb8434fa5bfc248e5910cb3.png?
[20210129163739875.png_pic_center]: /images/20221023/e36efb43464f475cb02f7c7a8aa77f0e.png
[20210129163754794.png]: /images/20221023/c5abd57706b34504abfff6ea8051743d.png?
[20210129163910966.png_pic_center]: /images/20221023/98af054bda9d4a2286fc08f16c7a9eff.png
[20210129164304490.png]: /images/20221023/d69c77ec91a647edab5e90a18d311568.png?
[20210129163942734.png]: /images/20221023/300ac047fc3c473185da32017c4a9a6d.png?
[20210129163955580.png_pic_center]: /images/20221023/7baefc2c663b4c5b8d6a0eaad41326ec.png
[20210129164013144.png_pic_center]: /images/20221023/2f6cbf74d207447a9713025a5b219d84.png
[basic-error-controller]: http://localhost:8080/swagger-ui.html#/basic-error-controller
[20210129164025349.png_pic_center]: /images/20221023/9001000a64754fdb80b9e59014baac9f.png
[20210129164036364.png]: /images/20221023/0e7a4177f0c24dafb12403d7264742bb.png?
[20210129164048668.png_pic_center]: /images/20221023/48282ea2d5894fbe98a9a6386c81fbfd.png
[20210129164100750.png]: /images/20221023/7cc71e1eaa8e470c9a8c88855b6c672f.png?
[20210129164110550.png]: /images/20221023/570167f7dec84d0c8f0553f8459428f7.png?
[20210129225447165.png_pic_center]: /images/20221023/5e602c24e64447cf98446fe50a42512b.png
[20210129225421860.png_pic_center]: /images/20221023/280c2bb72e29452796f2b18a4e7e3009.png
[20210129225432117.png]: /images/20221023/d51e7e489b4b4c359db5133cd25d808d.png?