SpringMVC整合SwaggerUI

文章目录

SpringMVC整合SwaggerUI

网上介绍Swagger整合的文章很多，但都是东拼西凑，抄来抄去，讲不清楚重点。本文的目的就是希望那些从来没有接触过Swagger的朋友能按照本文的步骤快速实现SpringMVC和SwaggerUI的整合，在界面上看到自己的API介绍。如果想深入研究Swagger，本文也附上了相关链接供参考。最终效果如下所示。

SpringMVC整合SwaggerUI

概念介绍

初接触Swagger的朋友一定会被一堆专业名词搞得晕头转向，什么SpringFox、Swagger、SwaggerUI、SwaggerEditor、SwaggerCodegen、SwaggerInspector等。想做整合，了解下面三个概念即可，想全部了解，可以参考文末链接1，有详细介绍。

Swagger: 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单说就是一套生成文档的框架，要想将其整合进自身的项目，需要实现相关的接口。
SwaggerUI: 一套前端界面，用于发送请求给后台的Controller，读取后台返回的JSON信息并渲染成相关漂亮的页面。
SpringFox: Swagger规范的Spring实现，第三方提供升级和维护。

了解了上述概念，本文要做的事情也就清楚了：利用第三方提供的SpringFox将自身项目中的RESTful API在SwaggerUI中显示出来。

编写整合代码

接下来我们展示如何整合2.x版本的swagger-ui。

index.html文件修改

对于基于SpringMVC的web项目来说，毫无疑问要把上述资源放到webapp目录下。接下来打开index.html文件，需要对文档做几处修改，如下图所示。

SpringMVC整合SwaggerUI

图中第一个红框放开了两段注解，目的是让swagger-ui的显示语言为中文。第二个红框是根据自身项目的名称来指定文档的访问路径。

需要注意的是，通常的访问路径是/项目名/v2/api-docs，项目名可变，其他固定。为什么其他部分固定呢？因为springfox中路径的默认值就是/项目名/v2/api-docs。需要变更的话还得自己写配置文件，比较麻烦，感兴趣的朋友可参考文末链接2。

图中在访问url中新增了/rest，这是因为我的项目中所有RESTful API都在该路径下。这里所新增的路径在后面swagger的配置文件中都需要加上。

maven中引入依赖

上文已对springfox的概念做了介绍，我们的springmvc项目中需要使用该工具，首先得添加依赖项。

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>18.0</version> </dependency>

不同版本的springfox的依赖项最低版本也不一样，需要自行修改。

springmvc配置文件中配置资源路径

资源路径配置没什么好说的，原理和配置js、css等其他资源文件一样。

<!-- Swagger支持（暂时注释掉提高平台性能，需要此功能，可以放开注释）--> <context:component-scan base-package="springfox"/> <bean class="org.test.core.swagger.SwaggerConfig"/> <mvc:resources mapping="/swagger/" location="/swagger/"/>

编写swagger配置文件

swagger配置文件的作用是为了告诉springmvc在启动的时候启用springfox，并到配置的路径下扫描RESTful API。下面我们创建配置类，SwaggerConfig.java。

@Configuration @EnableSwagger2 public class SwaggerConfig { 
     @Bean public Docket api() { 
     return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .pathMapping("/rest/")//对请求的路径增加rest前缀 .globalOperationParameters(setHeaderToken()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //只过滤包含有ApiOperation注解的方法 .paths(PathSelectors.any()) //对所有的路径进行监控 .build(); } private ApiInfo apiInfo() { 
     return new ApiInfoBuilder() .title("文档标题") .description("文档概述。") .contact(new Contact("公司名", "公司网址", "联系人邮箱")) .version("版本号") .build(); } private List<Parameter> setHeaderToken() { 
     ParameterBuilder tokenPar = new ParameterBuilder(); List<Parameter> pars = new ArrayList<>(); tokenPar.name("X-AUTH-TOKEN").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build(); pars.add(tokenPar.build()); return pars; } }

上述配置类具有通用性，该填写的内容也已注明。需要注意的是，如果我们希望访问每个API的时候都需要带TOKEN，那么就需要配置setHeaderToken()，这里配置的TOKEN信息会显示在每个API的第一个参数上。反之则不用调用。

如果想对springfox的原理深入了解，可参考文末链接3。

效果展示

根据上述配置类，swagger-ui上显示的内容如下：

SpringMVC整合SwaggerUI

如果配置了访问TOKEN，每个API的效果如下，一一对照上述的配置就知道setHeaderToken()方法中每部分的作用了。

SpringMVC整合SwaggerUI

整合时可能出现的异常

如果项目能编译通过，但是启动时报下述异常，可能就是SpringMVC中相关配置缺失了。

Error creating bean with name ‘documentationPluginsBootstrapper’ defined in URL…

Error creating bean with name ‘webMvcRequestHandlerProvider’ defined in URL…

No qualifying bean of type [org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping] found for dependency…

问题分析

上述嵌套异常出现的根本原因是没有找到RequestMappingInfoHandlerMapping的实现类，无法Autowired。

在springmvc中源码找到该类，发现它是一个抽象类。Ctrl+T一下，发现该类的实现为RequestMappingHandlerMapping。所以问题原因就是没有在springmvc.xml的配置文件中配置该bean。

问题解决

springmvc.xml中添加下述配置即可解决问题。因为添加了RequestMappingHandlerMapping就得添加RequestMappingHandlerAdapter，否则会报找不到适配器的错误。

<!-- 避免IE执行AJAX时,返回JSON出现下载文件 --> <bean id="mappingJacksonHttpMessageConverter" class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter"> <property name="supportedMediaTypes"> <list> <value>text/html;charset=UTF-8</value> <value>text/json;charset=UTF-8</value> <value>application/json;charset=UTF-8</value> </list> </property> </bean> <!-- ResponseBody返回字符串带双引号解决 --> <bean id="stringHttpMessageConverter" class="org.springframework.http.converter.StringHttpMessageConverter"> <constructor-arg value="UTF-8" index="0"/> <property name="supportedMediaTypes"> <list> <value>text/plain;charset=UTF-8</value> </list> </property> </bean> <!-- 注册handler method和request的mapping关系。 --> <bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping"/> <!-- 启动Spring MVC的注解功能，完成请求和注解POJO的映射， 配置一个基于注解的定制的WebBindingInitializer，解决日期转换问题，方法级别的处理器映射 --> <bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter"> <property name="cacheSeconds" value="0"/> <property name="messageConverters"> <list> <ref bean="stringHttpMessageConverter"/> <!--先进行string转换--> <ref bean="mappingJacksonHttpMessageConverter"/><!-- json转换器 --> </list> </property> </bean>

总结

本文先对swagger的相关概念进行了介绍，接着详细介绍了整合步骤，并对实际踩过的坑进行了剖析。详细只要按照本文的步骤，整个自己项目的swagger-ui是件很容易的事情。

参考资料

Swagger介绍及使用
Spring boot中使用springfox来生成Swagger Specification小结
API管理工具Swagger介绍及Springfox原理分析

发布者：全栈程序员-站长，转载请注明出处：https://javaforall.net/231668.html原文链接：https://javaforall.net

SpringMVC整合SwaggerUI