为什么要用Swagger?

首先说一下需求：最近公司要开发一个小程序，我负责后台的接口开发。公司为了规范接口文档要统一使用YAPI 进行管理。YAPI支持Swagger 格式json文件导入，所以准备将公司的一个老项目接入Swagger2。在集成的过程中遇到一些问题，特意写这篇文章与大家分享。希望有同样需求的你少走些弯路。

项目环境版本

项目Spring版本： 3.2.2.RELEASE ，并且该项目不是mavne项目。

maven项目搭建步骤

Spring4 并且是maven项目的话集成相对简单一些。集成的步骤如下：
引入Swagger2的2个核心依赖即可，

        <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency>

然后就是配置Swagger 的配置类，配置类具体内容如下：

package com.bfsuol.swagger;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select()// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).apis(RequestHandlerSelectors.basePackage("com.bfsuol.app.interfaces.controller")).build().apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("开放接口API").description("HTTP对外开放接口").version("1.0.0").termsOfServiceUrl("http://xxx.xxx.com").license("LICENSE").licenseUrl("http://xxx.xxx.com").build();}
}

maven项目使用步骤参考和光同尘ss 博主的文章 你也可以点击查看原文的具体操作步骤 Maven+SpringMVC+SwaggerUI

Spring3 项目集成Swagger中遇到的问题

整理jar包的方法

但是我们的项目是非mavne项目。
我的做法是创建mavne项目，然后引入上面2个核心依赖然后去本地仓库中复制jar包，jar包的具体路径如下图红色框所示。

缺少jar包的问题

整理完jar包复制到我们的jar 项目中。第一次尝试报如下图错误：

Caused by: java.io.FileNotFoundException: class path resource [org/mapstruct/Mapper.class] cannot be opened because it does not existat org.springframework.core.io.ClassPathResource.getInputStream(ClassPathResource.java:157)at org.springframework.core.type.classreading.SimpleMetadataReader.<init>(SimpleMetadataReader.java:50)at org.springframework.core.type.classreading.SimpleMetadataReaderFactory.getMetadataReader(SimpleMetadataReaderFactory.java:80)at org.springframework.core.type.classreading.CachingMetadataReaderFactory.getMetadataReader(CachingMetadataReaderFactory.java:102)at org.springframework.core.type.classreading.SimpleMetadataReaderFactory.getMetadataReader(SimpleMetadataReaderFactory.java:76)at org.springframework.context.annotation.ConfigurationClassParser.getImports(ConfigurationClassParser.java:298)at org.springframework.context.annotation.ConfigurationClassParser.getImports(ConfigurationClassParser.java:300)at org.springframework.context.annotation.ConfigurationClassParser.doProcessConfigurationClass(ConfigurationClassParser.java:231)at org.springframework.context.annotation.ConfigurationClassParser.processConfigurationClass(ConfigurationClassParser.java:154)at org.springframework.context.annotation.ConfigurationClassParser.parse(ConfigurationClassParser.java:131)at org.springframework.context.annotation.ConfigurationClassParser.doProcessConfigurationClass(ConfigurationClassParser.java:225)at org.springframework.context.annotation.ConfigurationClassParser.processConfigurationClass(ConfigurationClassParser.java:154)at org.springframework.context.annotation.ConfigurationClassParser.processImport(ConfigurationClassParser.java:349)at org.springframework.context.annotation.ConfigurationClassParser.doProcessConfigurationClass(ConfigurationClassParser.java:233)at org.springframework.context.annotation.ConfigurationClassParser.processConfigurationClass(ConfigurationClassParser.java:154)at org.springframework.context.annotation.ConfigurationClassParser.parse(ConfigurationClassParser.java:131)at org.springframework.context.annotation.ConfigurationClassPostProcessor.processConfigBeanDefinitions(ConfigurationClassPostProcessor.ja

在mavne项目中搜索该类发现该类在mapstruct-1.1.0.Final.jar包中我们将该jar包复制到我们的项目中。

声明@EnableWebMvc报错问题

第二次尝试没有报上面的错误但是报如在错误：

Caused by: java.lang.ClassCastException: org.springframework.web.accept.ContentNegotiationManagerFactoryBean$$EnhancerByCGLIB$$dbb6606b cannot be cast to org.springframework.web.accept.ContentNegotiationManagerat org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration$$EnhancerByCGLIB$$269d1c34.mvcContentNegotiationManager(<generated>)at org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport.requestMappingHandlerMapping(WebMvcConfigurationSupport.java:196)at org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration$$EnhancerByCGLIB$$269d1c34.CGLIB$requestMappingHandlerMapping$19(<generated>)at org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration$$EnhancerByCGLIB$$269d1c34$$FastClassByCGLIB$$ad3fcfb7.invoke(<generated>)at org.springframework.cglib.proxy.MethodProxy.invokeSuper(MethodProxy.java:228)at org.springframework.context.annotation.ConfigurationClassEnhancer$BeanMethodInterceptor.intercept(ConfigurationClassEnhancer.java:286)at org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration$$EnhancerByCGLIB$$269d1c34.requestMappingHandlerMapping(<generated>)at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43

去掉 @EnableWebMvc 因为配置文件中已经配置了mvc:annotation-driven
在次启动没有报错。

Spring版本不兼容的问题

满心欢喜的去访问swagger-ui.html页面取查看我们定义的接口，结果报如下错误。此时我的内心是崩溃的。

java.lang.NoSuchMethodError: org.springframework.web.util.UriComponentsBuilder.fromHttpRequest(Lorg/springframework/http/HttpRequest;)Lorg/springframework/web/util/UriComponentsBuilder;at springfox.documentation.swagger2.web.HostNameProvider.componentsFrom(HostNameProvider.java:44)at springfox.documentation.swagger2.web.Swagger2Controller.getDocumentation(Swagger2Controller.java:93)at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)at java.lang.reflect.Method.invoke(Method.java:498)

从错误中我们发先该类未定义但是spring的jar包确实存在。明显是Spring版本太低的问题。现在解决方式只有2种。
1 升级Spring版本
2 降低 Swagger 的版本
我这里选择了降低 Swagger 的版本，百度搜索swagger的pom依赖

这里选择最低版本再次进行尝试。如下图所示我们集成成功！

需要集成的jar包的请点击链接去下载（仅仅是swagger 先关jar没有spring的jar吧哈）：https://download.csdn.net/download/ljk126wy/11099420

Spring3集成Swagger2遇到问题总结相关推荐

Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
springboot集成swagger2测试接口
springboot集成swagger2测试接口 1.需要的依赖 2.开始编写一个swagger2 3.演示效果图片 1.需要的依赖 <dependency><groupId> ...
springboot集成swagger2多模块中文配置详细步骤，解决集成mybatis或mybatis-plus无法正常使用问题
springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题参考文章: (1)springboot集成swagger2多模块中文配 ...
13.9 SpringBoot集成Swagger2中遇到的问题
13.9 SpringBoot集成Swagger2中遇到的问题我们在使用SpringBoot集成Swagger2中,访问:http://127.0.0.1:8188/swagger-ui.html ...
springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
springboot集成swagger2，构建优雅的Restful API
springboot集成swagger2,构建优雅的Restful API 转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/ ...
SpringBoot集成Swagger2自动生成友好的RestApi测试页面及文档
springBoot集成swagger2 水煮鱼又失败了 https://www.jianshu.com/p/002ce2f26103 1 背景 springBoot作为微服务首选框架,为其他服务提供 ...
【快速上手系列】使用Springboot集成Swagger2的简单使用测试
[快速上手系列]使用Springboot集成Swagger2的简单使用测试简介 Swagger2是为了解决企业中接口(api)中定义统一标准规范的文档生成工具. 尤其是前后端分离时对一些业务接口也不 ...
SpringBoot集成Swagger2、Swagger2和Swagger3的区别Swagger的注解学习
Swagger的介绍 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新. 随着前后端 ...

Spring3集成Swagger2遇到问题总结