前言

最近公司需要写API文档，点名要用swagger，花了两天时间才折腾完。主要的坑都在配置上，springmvc集成swagger不太方便，如果是用springboot的话就会快很多。话不多说先上代码，后面写注意事项和爬坑记录。

POM引入

     <!--     swagger配置 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.4.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.4.0</version></dependency>

Swagger配置类

package com.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*** @Author: Klein* @Date: 2022/5/27* @desc: swagger配置类*/@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig{@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build().pathMapping("/swagger") // 方法的url映射路径.apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger测试API").description("测试使用").version("1.0.0").termsOfServiceUrl("http://xxx.xxx.com").license("license").licenseUrl("http://xxx.xxx.com").build();}
}

.pathMapping(“/swagger”)的作用是在swagger的方法路径前加上/swagger，我的项目中如果不加路径是错的。
示例：红色方框中就是pathMapping

spring-mvc.xml设置

 <!-- 开启自动映射 --><mvc:annotation-driven/><!-- swagger --><bean name="SwaggerConfig" class="com.swagger.config.SwaggerConfig"/><mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" /><mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

如果有在web.xml里配置拦截器

加入这两行

     <url-pattern>/swagger/*</url-pattern><url-pattern>/api-docs</url-pattern>

测试类

package com.swagger.controller;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;/*** @Author: Klein* @Date: 2022/5/27* @desc: swagger测试类*/
@Controller
@RequestMapping("test")
@Api(value = "Test")
public class TestController {@RequestMapping("index")@ResponseBody@ApiOperation(value = "进入首页面", httpMethod = "GET", notes = "get index", response = String.class)public String index(){return "index";}}

准备就绪

启动项目后在进入http://IP地址:端口号/项目名称/swagger/swagger-ui.html就能看到以下图。

整合swagger的代码方面没啥难度，主要是在配置上特别麻烦，下面列几点注意事项。

注意事项

1. SpringMVC版本最好在3.0以上。
2. 编译报错提示没找到方法的话，去检查依赖包是否被覆盖。
3. 如果进入swagger-ui.html报404的话，重点检查拦截器。

爬坑经历

一开始导入依赖包时出现项目启动失败的情况，报错是没有找到springfox.xxx的方法啥的，仔细观察依赖发现主要是两个包被公司框架包覆盖了，分别是com.fasterxml:classmate（需要1.3.1）和com.google.guava（需要18.0），修改框架jar包中的pom文件后成功运行。

成功启动项目后，发现图片全都加载不出来，前端json解析全部报错，这下给我整懵了，又是花了好长时间排查，发现：

1. 如果配置类加了注解@EnableWebMvc
2. spring-mvc.xml文件里加了 mvc:annotation-driven

都会导致该问题，查看《SpringMVC关于json、xml自动转换的原理研究》该文档后发现问题，因为我的项目Spring版本比较落后，使用AnnotationMethodHandlerAdapter做了一个json转换器，然后启用mvc自动映射时会覆盖AnnotationMethodHandlerAdapter，所以导致json前端相关的全部报错。

 <!-- 启动Spring MVC的注解功能，完成请求和注解POJO的映射， 方法级别的处理器映射 --><beanclass="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter"><property name="cacheSeconds" value="0" /><property name="messageConverters"><list><ref bean="mappingJacksonHttpMessageConverter" /><!-- json转换器 --></list></property></bean>

其中这篇文档《spring源码学习》更是直接点出了为什么自动映射后json转换会失效的关键点。

没错，这个消息转换器他们默认是不加载的。找到问题后，就开始改写spring-mvc.xml里的配置文件。

 <!-- 启动Spring MVC的注解功能，完成请求和注解POJO的映射，方法级别的处理器映射 --><beanclass="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter"><property name="cacheSeconds" value="0" /><property name="messageConverters"><bean id="mappingJacksonHttpMessageConverter"class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter"><property name="supportedMediaTypes"><list><value>text/html;charset=UTF-8</value></list></property></bean></property></bean><!-- 开启自动映射 --><mvc:annotation-driven/>

主要就是将AnnotationMethodHandlerAdapter换成了RequestMappingHandlerAdapter。
主要问题都解决了，启动项目后发现直接进swagger-ui.html会报404，一看就知道是被拦截了，先登陆系统后再进入就正常了。后续再改写下拦截器相关配置来解决该问题。
到目前为止前前后后花了两天时间，过程虽然很折磨但是对SpringMVC的底层有了更深入的了解，发现了自己的一大短板，就是对底层架构的了解非常差，后续得多看看SpringMVC的相关的书。

参考文章

https://wenku.baidu.com/view/ab68139daeaad1f347933f2b.html
https://blog.csdn.net/weixin_34304013/article/details/90224343
https://blog.51cto.com/jeecg/3190480
https://www.cnblogs.com/jeasy/articles/10832283.html

SpringMVC整合Swagger2相关推荐

03、Swagger2和Springmvc整合详细记录（爬坑记录）
时间内容备注 2018年6月18日基本使用 spirngmvc整合swagger2 开始之前这个系列博文基本是,在项目的使用中一些模块的内容记录,但是后期逐渐优化,不单单是整合内容. swagg ...
Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例
文章目录一.Swagger 简介二.Springfox 简介三.Springfox2.9.2 常用注解四.SpringBoot 整合 Swagger2 4.1 引入Maven依赖 4.2 项目 ...
SpringMVC整合fastdfs-client-java实现web文件上传下载
为什么80%的码农都做不了架构师?>>> 版权声明:本文为博主原创文章,转载请标明出处(http://blog.csdn.net/wlwlwlwl015)Thanks. 目录( ...
springmvc整合redis架构搭建实例
新换环境,又有新东西可以学习了,哈皮! 抽空学习之余看了一下redis,个人对Springmvc的爱是忠贞不渝,所以整理了一下Springmvc整合redis的环境搭建.分享学习. 第一步 : 创建 ...
六：Dubbo与Zookeeper、SpringMvc整合和使用
DUBBO与ZOOKEEPER.SPRINGMVC整合和使用互联网的发展,网站应用的规模不断扩大,常规的垂直应用架构已无法应对,分布式服务架构以及流动计算架构势在必行,Dubbo是一个分布式服务框架 ...
整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
【转】Dubbo_与Zookeeper、SpringMVC整合和使用（负载均衡、容错）
原文链接:http://blog.csdn.net/congcong68/article/details/41113239 互联网的发展,网站应用的规模不断扩大,常规的垂直应用架构已无法应对,分布式服 ...
Dubbo与Zookeeper、SpringMVC整合和使用（负载均衡、容错）（转）
互联网的发展,网站应用的规模不断扩大,常规的垂直应用架构已无法应对,分布式服务架构以及流动计算架构势在必行,Dubbo是一个分布式服务框架,在这种情况下诞生的.现在核心业务抽取出来,作为独立的服务,使 ...
SpringMVC整合MongoDB
首先,在pom文件中新增spring-data-mongodb的依赖: <dependency> <groupId>org.springframework.data</g ...

SpringMVC整合Swagger2