swagger配置信息详解

最新推荐文章于 2024-03-21 21:02:44 发布

keavykk

最新推荐文章于 2024-03-21 21:02:44 发布

阅读量4k

点赞数 1

文章标签： spring boot

原文链接：https://blog.csdn.net/weixin_43935927/article/details/113395427?ops_request_misc=&request_id=&biz_id=102&utm_term=docket%E5%AF%B9%E8%B1%A1&utm_medium=distribute.pc_search_result.none-task-blog-2~all~sobaiduweb~default-5-113395427.142^v7^control,157^v4^con

版权

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

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

使用 Swagger 总的分为两步：

写配置类
使用注解

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

创建配置类，启动 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>

}

至此，我们其实已经能将 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>

}

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>

}

然后重启 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组”);
}

在这里插入图片描述

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();

}

重启项目后，可以看到，原先的 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>

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>

}

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

keavykk

关注

1
点赞
踩
4

收藏

觉得还不错? 一键收藏
0
评论
swagger配置信息详解

先来说说 Swagger 有什么用，相较于使用 markdown 或者 word 写接口文档，Swagger 自动生成 API 文档，然后在 web 端暴露，并且 API 文档与 API 定义同步更新，这解决了前后端交互时接口更改但协商不及时的问题。另外，Swagger 还内置了在线...
复制链接

扫一扫