SpringMVC整合SwaggerUI

最新推荐文章于 2024-08-07 04:16:44 发布

星悬_月

最新推荐文章于 2024-08-07 04:16:44 发布

阅读量1.2k

点赞数 1

分类专栏：开发笔记文章标签： springmvc swagger-ui springfox

本文链接：https://blog.csdn.net/u012441819/article/details/100972335

版权

开发笔记专栏收录该内容

13 篇文章 1 订阅

订阅专栏

SpringMVC整合SwaggerUI

文章目录

SpringMVC整合SwaggerUI

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

概念介绍

初接触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文件，需要对文档做几处修改，如下图所示。

图中第一个红框放开了两段注解，目的是让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上显示的内容如下：

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

整合时可能出现的异常

如果项目能编译通过，但是启动时报下述异常，可能就是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>