swagger配置信息详解

先来说说 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>

   
   

   
   
1
2
3
4
5
6
7
8
9
10

注意：本篇是基于 SpringBoot 来构建

1. Swagger 是在 web 端显示，所以还需要引入 starter-web
2. Swagger2 要求 JDK 版本至少是 1.8，否则无法运行

使用 Swagger 总的分为两步：

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

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

创建配置类，启动 Swagger

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

下面，我们新建一个 SwaggerConfig：

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
<span class="token annotation punctuation">@Bean</span> <span class="token comment">// 构建并配置 Docket 对象</span>
<span class="token keyword">public</span> Docket <span class="token function">docket</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8

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

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

1.Docket 源码分析

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

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

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

2.DocumentationType 文档类型

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

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

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

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
<span class="token annotation punctuation">@Bean</span> <span class="token comment">// 构建并配置 Docket 对象</span>
<span class="token keyword">public</span> Docket <span class="token function">docket</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

3.ApiInfo 基本信息

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

可以看到，它提供了 8 个可以配置属性，根据名字也能猜出其中的意思。

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

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

现在我们来配置自己的 ApiInfo

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

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
<span class="token annotation punctuation">@Bean</span> <span class="token comment">// 构建并配置 Docket 对象</span>
<span class="token keyword">public</span> Docket <span class="token function">docket</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token comment">// 构建基本配置信息</span>
<span class="token keyword">public</span> ApiInfo <span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">ApiInfoBuilder</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">title</span><span class="token punctuation">(</span><span class="token string">"文档标题"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">description</span><span class="token punctuation">(</span><span class="token string">"测试的接口文档"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">version</span><span class="token punctuation">(</span><span class="token string">"v2.0"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">termsOfServiceUrl</span><span class="token punctuation">(</span><span class="token string">"baidu.com"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">contact</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">Contact</span><span class="token punctuation">(</span><span class="token string">"A minor"</span><span class="token punctuation">,</span> <span class="token string">"https://blog.csdn.net/weixin_43935927"</span><span class="token punctuation">,</span> <span class="token string">"3132266573@qq.com"</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20

然后重启 SpringBoot 项目

4.ApiSelectorBuilder 扫描接口

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

点开 ApiSelectorBuilder 源码：

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

1）requestHandlerSelector

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

• 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 注解（见下一篇）另一种是在 Docket 上增加筛选。两种方式的区别是，Docket 配置的规则，可以对多个接口器过滤作用，而 @ApiIgnore 只能作用于单个接口。

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

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

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

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

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

好了，现在我们来看一下在 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();
}

 
 

 
 
1
2
3
4
5
6
7
8
9

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

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

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20

6.useDefaultResponseMessages 默认状态码

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

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

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11

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

7.enabled 是否启动 Swagger

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

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

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

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

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
<span class="token annotation punctuation">@Bean</span> <span class="token comment">// 构建并配置 Docket 对象</span>
<span class="token comment">// 注：这里注入了 Environment 对象，目的是获取系统环境</span>
<span class="token keyword">public</span> Docket <span class="token function">docket</span><span class="token punctuation">(</span>Environment environment<span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>

    <span class="token comment">// 设置要显示 swagger 的环境（dev 或者 test）</span>
    Profiles of <span class="token operator">=</span> Profiles<span class="token punctuation">.</span><span class="token function">of</span><span class="token punctuation">(</span><span class="token string">"dev"</span><span class="token punctuation">,</span> <span class="token string">"test"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token comment">// 判断当前是否处于该环境</span>
    <span class="token keyword">boolean</span> flag <span class="token operator">=</span> environment<span class="token punctuation">.</span><span class="token function">acceptsProfiles</span><span class="token punctuation">(</span>of<span class="token punctuation">)</span><span class="token punctuation">;</span>

    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">enable</span><span class="token punctuation">(</span>flag<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">useDefaultResponseMessages</span><span class="token punctuation">(</span><span class="token boolean">false</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment">// 返回 ApiSelectorBuilder</span>
            <span class="token punctuation">.</span><span class="token function">apis</span><span class="token punctuation">(</span>RequestHandlerSelectors<span class="token punctuation">.</span><span class="token function">basePackage</span><span class="token punctuation">(</span><span class="token string">"com.xupt.yzh.testswagger.controller"</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token comment">// 接口扫描方案</span>
            <span class="token punctuation">.</span><span class="token function">paths</span><span class="token punctuation">(</span>PathSelectors<span class="token punctuation">.</span><span class="token function">any</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token comment">// 接口路径过滤方案</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token punctuation">}</span>

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23

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

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

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

完整代码

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
<span class="token annotation punctuation">@Bean</span> <span class="token comment">// 构建并配置 Docket 对象</span>
<span class="token comment">// 注：这里注入了 Environment 对象，目的是获取系统环境</span>
<span class="token keyword">public</span> Docket <span class="token function">docket</span><span class="token punctuation">(</span>Environment environment<span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>

    <span class="token comment">// 设置要显示 swagger 的环境（dev 或者 test）</span>
    Profiles of <span class="token operator">=</span> Profiles<span class="token punctuation">.</span><span class="token function">of</span><span class="token punctuation">(</span><span class="token string">"dev"</span><span class="token punctuation">,</span> <span class="token string">"test"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token comment">// 判断当前是否处于该环境</span>
    <span class="token keyword">boolean</span> flag <span class="token operator">=</span> environment<span class="token punctuation">.</span><span class="token function">acceptsProfiles</span><span class="token punctuation">(</span>of<span class="token punctuation">)</span><span class="token punctuation">;</span>

    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">enable</span><span class="token punctuation">(</span>flag<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">useDefaultResponseMessages</span><span class="token punctuation">(</span><span class="token boolean">false</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment">// 返回 ApiSelectorBuilder</span>
            <span class="token punctuation">.</span><span class="token function">apis</span><span class="token punctuation">(</span>RequestHandlerSelectors<span class="token punctuation">.</span><span class="token function">basePackage</span><span class="token punctuation">(</span><span class="token string">"com.xupt.yzh.testswagger.controller"</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token comment">// 接口扫描方案</span>
            <span class="token punctuation">.</span><span class="token function">paths</span><span class="token punctuation">(</span>PathSelectors<span class="token punctuation">.</span><span class="token function">any</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token comment">// 接口路径过滤方案</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token punctuation">}</span>

<span class="token comment">// 构建基本配置信息</span>
<span class="token keyword">public</span> ApiInfo <span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">ApiInfoBuilder</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">title</span><span class="token punctuation">(</span><span class="token string">"文档标题"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">description</span><span class="token punctuation">(</span><span class="token string">"测试的接口文档"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">version</span><span class="token punctuation">(</span><span class="token string">"v2.0"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">termsOfServiceUrl</span><span class="token punctuation">(</span><span class="token string">"baidu.com"</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">contact</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">Contact</span><span class="token punctuation">(</span><span class="token string">"A minor"</span><span class="token punctuation">,</span> <span class="token string">"https://blog.csdn.net/weixin_43935927"</span><span class="token punctuation">,</span> <span class="token string">"3132266573@qq.com"</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token annotation punctuation">@Bean</span>
<span class="token keyword">public</span> Docket <span class="token function">docket2</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">groupName</span><span class="token punctuation">(</span><span class="token string">"打工人2组"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token annotation punctuation">@Bean</span>
<span class="token keyword">public</span> Docket <span class="token function">docket3</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{<!-- --></span>
    <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">Docket</span><span class="token punctuation">(</span>DocumentationType<span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">groupName</span><span class="token punctuation">(</span><span class="token string">"打工人3组"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23
• 24
• 25
• 26
• 27
• 28
• 29
• 30
• 31
• 32
• 33
• 34
• 35
• 36
• 37
• 38
• 39
• 40
• 41
• 42
• 43
• 44
• 45

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