【实战】记一次老项目的swagger整合

1.背景

这两天接到一个整合swagger的任务，本以为很简单，预计两小时内完成，没想到其中有太多的坑，整了两天才完成。
首先项目是一个比较老的项目，之前用的servlet，目前在重构为springmvc。所以有一部分servlet，一部分springmvc。spring配置方面也有很多不规范的地方，这也为我后面踩坑埋下伏笔。

2.坑坑

2.1 spring版本

项目用的spring版本为4.3.1，在引入springfox-swagger2和springfox-swagger-ui后项目启动报错。原因是springfox-swagger2在集成的时候，已经引入了spring的相关jar，且与项目中的spring版本不一致，导致了冲突，需要排除掉swagger中的spring依赖

<dependency> 
            <groupId>io.springfox</groupId> 
            <artifactId>springfox-swagger2</artifactId> 
            <version>2.4.0</version> 
            <exclusions> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-core</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-beans</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-context</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-context-support</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-aop</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-tx</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-orm</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-jdbc</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-web</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-webmvc</artifactId> 
                </exclusion> 
                <exclusion> 
                    <groupId>org.springframework</groupId> 
                    <artifactId>spring-oxm</artifactId> 
                </exclusion> 
            </exclusions> 
        </dependency> 
        <dependency> 
            <groupId>io.springfox</groupId> 
            <artifactId>springfox-swagger-ui</artifactId> 
            <version>2.4.0</version> 
        </dependency>

2.2 web.xml

加swagger依赖，加swagger配置，加swagger注解后。启动，访问http://xxxx:8080/platform_web/swagger-ui.html#/ ,页面空白，F12…404了
说明请求没有被转发。去web.xml看一眼dispatcherservlet怎么配的，发现url-pattern是.do。额，没有匹配呀，那我自己写吧。总不能把人家的改成/吧

<servlet-mapping>
        <servlet-name>dispatcherServlet</servlet-name>
        <url-pattern>*.do</url-pattern>
        <!-- 为swagger配置额外的pattern-->
        <url-pattern>/v2/api-docs</url-pattern>
        <url-pattern>/v2/api-docs-ext</url-pattern>
        <url-pattern>/configuration/security</url-pattern>
        <url-pattern>/configuration/ui</url-pattern>
        <url-pattern>/swagger-resources</url-pattern>
        <url-pattern>/swagger-resources/configuration/security</url-pattern>
        <url-pattern>/swagger-resources/configuration/ui</url-pattern>
    </servlet-mapping>

2.3 spring配置，springmvc配置（配置不规范，重构两行泪）

再启动，文档描述出来了，但接口还没有内容…F12看请求资源，全是200，所以不是资源请求的问题。但是我swagger请求中配置了扫描包，包里的类也加上了swagger注释了呀。.apis(RequestHandlerSelectors.basePackage(“work”)) //扫描的包。说明没扫描到包或者说没拿到包中的依赖。看一下spring配置文件，确实配置了，spring容器肯定有这些bean。springmvc配置文件中并没有包扫描的配置。严格的说controller应该注册在springmvc容器中，但在spring容器中也不是不可以呀，spirng和springmvc是父子容器的关系，springmvc应该能正常的拿到spring容器中的bean呀。百度大法后，发现swagger好像比较傲娇，它只从springmvc容器中拿bean…好吧，那我把controller的bean调整到springmvc容器吧，同时移除掉spring容器中的controller（注意：swaggerconfig也应该注册在springmvc容器中）
（1）spring

 <!--排除掉swagger和controller-->
    <context:component-scan base-package="work,core,projectcore">
        <context:exclude-filter type="regex" expression="work.actionv.*" />
        <context:exclude-filter type="assignable" expression="swaggerConfig.SwaggerConfig"/>
    </context:component-scan>

（2）springmvc

<!--注入controller-->
	<context:component-scan base-package="work" use-default-filters="false">
		<context:include-filter type="regex" expression="work.actionv.*"/>
	</context:component-scan>
	<!--SwaggerConfig配置类注入-->
	<bean id="swaggerConfig" class="swaggerConfig.SwaggerConfig"/>

2.4 只显示一个接口（google大法好）

重启，接口列表出来了，但只有一个接口是什么鬼，我明明每个方法上都有注解啊。观察代码，发现由于每个mapping的url都相同，只是通过参数method来区分的

百度后得知swagger（openapi）的数据结构就是 path -> method -> operation ，没有通过参数区分的方式，所以多个url相同时只展示一条，也只有零星的几个帖子提到这个情况，而且大家一致认为没有什么好的解决方案。但我还不服气，google了一下发现了一种解决方案：docket配置enableUrlTemplating,[Springfox not generating different swagger entries for operations with same base path, but one endpoint has query parameters]