欢迎关注头条号：老顾聊技术

精品原创技术分享，知识的组装工

前言

上一篇文章介绍了前后端分离框架，如何设计一个简单易行的API文档，今天我们就介绍一下如何在SpringBoot2.x项目中应用此Swagger2框架，在使用过程中我们需要注意哪些方面

开始项目

首先，我们需要一个带有一些Rest Controller的Spring Boot应用程序，我使用了SpringFox 2.9.2和Spring Boot 2.1.12.RELEASE。

添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

创建Swagger2配置类

在项目的配置包下面创建Swagger2的配置类Swagger2Config

配置信息如下

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。

• @ EnableSwagger2支持Swagger 2的SpringFox支持。
• DocumentationType.SWAGGER_2告诉Docketbean我们正在使用Swagger规范的版本2。
• apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
• select()创建一个构建器，用于定义哪些控制器及其生成的文档中应包含哪些方法。
• apis()定义要包含的类（控制器和模型类）。这里我们包括所有这些，但您可以通过基础包，类注释等来限制它们。

SpringFox会将其检测为文档生成源。Controller和Model类。您可以在Docket配置中轻松配置它。我们可以使用.apis（RequestHandlerSelectors.any（）来包含所有类；当然我们也可以缩小到我们的基础包

• paths()允许您根据路径映射定义应包含哪个控制器的方法。我们现在包括所有这些，但您可以使用正则表达式等限制它。上面的代码.paths(PathSelectors.any())是代表匹配所有URL。

有时我们还需要只包含特定的URL路径。可能正在使用API??的多个版本以实现向后兼容，但不希望包含历史版本。也许API的某些部分是内部的，不应该是公共文档的一部分。无论哪种方式，也可以在Docket中配置基于URL匹配的这种包含。如

.paths(PathSelectors.ant("/v2/**"))

将其限制为某些正则表达式或Ant样式的路径模式，而不是匹配所有路径的任何路径。

将Swagger Core注释添加到模型类中

我们可以在实体类上面进行注释

类级别使用@ApiModel注释；字段级别@ApiModelProperty。@ApiModelProperty的示例对于提供示例值非常有用，这不仅适用于用户的指导，而且还可以在使用Swagger UI作为REST客户端来测试服务时预填充请求有效负载。Position属性很方便指定属性在文档中显示的顺序。首先提供重要或必需的属性或属于一起的组属性是有用的。否则，属性将按字母顺序列出。

将Swagger Core注释添加到控制器类

与使用Swagger核心注释注释模型类以提供其他元数据相同，您可以注释控制器及其方法和方法参数。

• @Api描述了整个控制器
• @ApiOperation用于方法级别的描述
• @ApiParam用于方法参数
• @ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明

配置到这里，基本的配置就结束了。那是不是就可以执行启动

404坑一

我们在启动后，请求http://localhost:8081/swagger-ui.html 直接报404错误；这个问题是因为我们的项目是纯的restful前后端分离的项目，我们在application.yml中配置了

spring.mvc.resources.add-mapping:false

将其注释掉熟悉的界面又回来了，这个配置是不自动给静态资源添加路径，导致swagger-ui.html找不到资源。怎么解决呢？修改一下Swagger2Config

上面的代码就是人为的把资源做一下映射关系

源码Bug坑二

细心的小伙伴在运行时，应用控制台打印时，会时不时的报异常，如下

java.lang.NumberFormatException: For input string: ""，出错的原因呢是因为 空字符串""无法转成Number。

我们找到Swagger包下抛出异常的类：

这个异常就是因为上面源码上面的判断条件有问题，如果example属性不配置的话，在属性是Integer类型时Long.valueOf(example)时就会报异常，解决方法：

io.springfox:springfox-swagger2:2.9.2中依赖了swagger-models的1.5.20版本，我们可以排除springfox-swagger2中的swagger-models依赖，导入io.swagger:swagger-models的1.5.21版本即可

静态资源404坑三

到现在为止，如果应用是一个纯粹的 REST Api 接口服务，那就基本没什么问题，但如果应用中仍然有视图模板、静态资源时，可能就会出现加载不到静态资源了。如果出现这个问题，那只要在Swagger配置类 SwaggerConfig 中加上静态资源路径映射即可：

//路径根据自己的项目去做映射
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

下面介绍企业项目中比较实用的用法

忽略不想生成文档的接口

某些Controller 不需要生成API文档的接口，可以通过@ApiIgnore忽略掉

生产环境关闭Swagger

swagger用来在开发阶段方便前后端开发。降低交流成本。但是版本上线之后，需要把swagger关闭。

在配置类Swagger2Config中加上条件注解

通过@ConditionalOnProperty(prefix = “swagger2”,value = {“enable”},havingValue = “true”)注解实现。

读取配置文件中前缀为swagger2的配置，属性名为enable，值为true。

当条件成立，此配置类被激活。

两个属性name以及havingValue，其中name用来从application.properties中读取某个属性值，如果该值为空，则返回false;

如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true;否则返回false。如果返回值为false，则该configuration不生效；为true则生效

swagger2:
	enable: true(在pro环境下不写此配置)

配置全局参数

在做前后端分离的项目中，每个接口中都会有相同的参数，如：token，用户令牌；那怎么方便的在Swagger中使用呢?我们在Swagger2Config配置类中

上面代码就达到了在每个接口上面加上了token参数，token是非必填的

总结

今天老顾介绍了swagger的一些实战，当然介绍了不是太完整，有些网上会有所介绍，老顾只是把一些重点，在这里阐述了。谢谢！！！

---End---

老顾的微服务网关分享课程，请大家多多支持

推荐阅读

a、dubbo如何处理业务异常，这个一定要知道哦！

b、企业级SpringBoot应用多个子项目配置文件规划、多环境支持（一）

c、企业级SpringBoot应用多个子项目配置文件规划、多环境支持（二）

d、企业级SpringBoot应用多个子项目配置文件之配置中心（三）

e、利用阿里开源工具进行排查线上CPU居高问题

f、阿里二面：如何快速排查死锁？如何避免死锁？

1、基于RocketMq的SpringCloud Stream框架实战入门

2、如何搭建消息中间件应用框架之SpringCloud Stream

3、面试必备：网关异常了怎么办？如何做全局异常处理？

4、Gateway网关系列(二)：SpringCloud Gateway入门实战，路由规则

5、Gateway网关系列开篇：SpringCloud的官方网关Gateway介绍

6、API网关在微服务架构中的应用，这一篇就够了

7、学习Lambda表达式看这篇就够了，不会让你失望的哦（续篇）

8、Lambda用在哪里？几种场景？

9、为什么会出现Lambda表达式，你知道吗？

10、不说“分布式事务”理论，直接上大厂阿里的解决方案，绝对实用

11、女程序员问到这个问题，让我思考了半天，Mysql的“三高”架构

12、大厂二面：CAP原则为什么只能满足其中两项？而不能同时满足

13、阿里P7二面：聊聊零拷贝的原理

14、秒杀系统的核心点都在这里，快来取

15、你了解如何利用token方式实现分布式Session吗？

16、Mysql索引结构演变，为什么最终会是那个结构呢？让你一看就懂

17、一场比赛涉及到的知识，用通俗易通的方式介绍并发协调

18、企业实战Redis全方面思考，你思考了吗？

19、面试题：Thread的start和run的区别

20、面试题：什么是CAS？CAS的作用以及缺点

21、如何访问redis中的海量数据？避免事故产生

22、如何解决Redis热点问题？以及如何发现热点？

23、如何设计API接口，实现统一格式返回？

24、你真的知道在生产环境下如何部署tomcat吗？

25、分享一线互联网大厂分布式唯一ID设计 之 snowflake方案

26、分享大厂分布式唯一ID设计方案，快来围观

27、你想了解一线大厂的分布式唯一ID生成方案吗？

28、你知道如何处理大数据量吗？(数据拆分篇)

29、如何永不迁移数据和避免热点? 根据服务器指标分配数据量(揭秘篇)

30、你知道怎么分库分表吗？如何做到永不迁移数据和避免热点吗？

31、你了解大型网站的页面静态化吗？

32、你知道如何更新缓存吗？如何保证缓存和数据库双写一致性？

33、你知道怎么解决DB读写分离，导致数据不一致问题吗？

34、DB读写分离情况下，如何解决缓存和数据库不一致性问题？

35、你真的知道怎么使用缓存吗？

36、如何利用锁，防止缓存击穿？重构思想的重要性

37、海量订单产生的业务高峰期，如何避免消息的重复消费？

38、你知道如何保障生产端100%消息投递成功吗？

39、微服务下的分布式session该如何管理？

40、阿里二面：filter、interceptor、aspect应如何选择？很多人中招

41、互联网架构重要组员CDN，很多高级开发都没有实操过，来看这里

42、阿里二面：CDN缓存控制原理，看看能不能难住你

43、SpringCloud Alibaba之Nacos多环境多项目管理

44、SpringCloud Alibaba系列之Nacos配置中心玩法

45、SpringCloud Alibaba之Nacos注册中心

46、SpringCloud Plus版本之SpringCloud Alibaba

47、SpringCloud Alibaba之Nacos集群、持久化

48、SpringCloud Alibaba之Nacos共享配置、灰度配置

49、SpringCloud Alibaba之Sentinel工作原理

50、SpringCloud Alibaba之Sentinel流控管理

51、SpringCloud Alibaba之Sentinel降级管理

52、SpringCloud Alibaba之Sentinel热点参数限流

53、SpringCloud Alibaba之Sentinel的API实战