前言

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

开始项目

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第1张图片

添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第2张图片

创建Swagger2配置类

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第3张图片

配置信息如下

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第4张图片

如上代码所示，通过@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注释添加到模型类中

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第5张图片

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

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

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

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第6张图片

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第7张图片

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

404坑一

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

1.  `spring.mvc.resources.add-mapping:false`

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第8张图片

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第9张图片

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

源码Bug坑二

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第10张图片

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

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第11张图片

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第12张图片

这个异常就是因为上面源码上面的判断条件有问题，如果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版本即可

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第13张图片

静态资源404坑三

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

1.  `//路径根据自己的项目去做映射`

2.  `registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");`

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

忽略不想生成文档的接口

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第14张图片

生产环境关闭Swagger

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

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第15张图片

通过@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环境下不写此配置)`

配置全局参数

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第16张图片

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第17张图片

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

总结

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

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）_第18张图片

Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）

前言

配置全局参数

总结

你可能感兴趣的:(Spring Boot 2.x使用Swagger2构建API文档及跳坑（二）)