前言
前一篇文章介绍了前端和后端分离框架，以及如何设计一个简单的API文档。今天，我们将介绍如何在springboot2中应用这个swagger2框架。X项目，以及在使用过程中需要注意哪些方面。
启动项目
首先，我们需要一个带有一些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匹配的这种包含。如
1. `.paths(PathSelectors.ant("/v2/**"))`
将其限制为某些正则表达式或Ant样式的路径模式，而不是匹配所有路径的任何路径。
将Swagger Core注释添加到模型类中
我们可以在实体类上面进行注释
类级别使用@ApiModel注释；字段级别@ApiModelProperty。@ApiModelProperty的示例对于提供示例值非常有用，这不仅适用于用户的指导，而且还可以在使用Swagger UI作为REST客户端来测试服务时预填充请求有效负载。Position属性很方便指定属性在文档中显示的顺序。首先提供重要或必需的属性或属于一起的组属性是有用的。否则，属性将按字母顺序列出。
将Swagger Core注释添加到控制器类
与使用Swagger核心注释注释模型类以提供其他元数据相同，您可以注释控制器及其方法和方法参数。
-
@Api描述了整个控制器
-
@ApiOperation用于方法级别的描述
-
@ApiParam用于方法参数
-
@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
配置到这里，基本的配置就结束了。那是不是就可以执行启动。
404坑一
1. `spring.mvc.resources.add-mapping:false`
将其注释掉熟悉的界面又回来了，这个配置是不自动给静态资源添加路径，导致swagger-ui.html找不到资源。怎么解决呢？修改一下Swagger2Config
上面的代码就是人为的把资源做一下映射关系。
源码Bug坑二
细心的小伙伴在运行时，应用控制台打印时，会时不时的报异常，如下：
1. `java.lang.NumberFormatException: For input string: ""，出错的原因呢是因为 空字符串""无法转成Number。`
</pre>
我们找到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 中加上静态资源路径映射即可：
1. `//路径根据自己的项目去做映射`2. `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则生效
1. `swagger2:`
2. `enable: true(在pro环境下不写此配置)`
</pre>
配置全局参数
在做前后端分离的项目中，每个接口中都会有相同的参数，如：token，用户令牌；那怎么方便的在Swagger中使用呢?我们在Swagger2Config配置类中
上面代码就达到了在每个接口上面加上了token参数，token是非必填的
总结
今天老顾介绍了swagger的一些实战，当然介绍了不是太完整，有些网上会有所介绍，老顾只是把一些重点，在这里阐述了。谢谢！！！