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

前言

上一篇文章介绍了前后端分离框架,如何设计一个简单易行的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匹配的这种包含。如

1.  `.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中配置了。

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的一些实战,当然介绍了不是太完整,有些网上会有所介绍,老顾只是把一些重点,在这里阐述了。谢谢!!!

推荐阅读更多精彩内容