虽然现在的项目基本都是用最新的版本，但是难免有些老项目还是使用了古老的版本。本文对SpringMVC 3.22版本的swagger配置进行了记录，希望能够帮助你跨越这些远古的坑。
Swagger : THE WORLD'S MOST POPULAR API FRAMEWORK
使用项目： http://git.oschina.net/durcframework/emptyProject
介绍：基于SpringMVC3.2.2 的封装框架durcframework
Swagger是Restfulf风格项目开发必不可少的工具，现在最新的是Swagger2,Swagger2的配置可以说是相当简单了。但是因为团队使用的基础项目是基于SpringMVC 3.2.2的权限管理系统所以碰到了很多坑。废话不多说，配置过程如下：
-
在pom.xml中添加依赖：
<!-- swagger API document --> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>0.6.5</version> </dependency> -
在
springMVC.xml（平时的SpringMVC项目中为xx-sevlet.xml）中添加如下配置：<!--swagger--> <mvc:annotation-driven /> <context:component-scan base-package="app.controller" /><!--需要扫描的包--> <context:property-placeholder location="classpath:/swagger.properties" /> <bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig" /> <context:annotation-config /> <mvc:default-servlet-handler /> -
在
classpth（mvn项目的classpath为src/main/resources）下添加swagger.properties文件,写入如下配置：documentation.services.version=1.0 documentation.services.basePath=http://localhost:8088/yourProjName/api-docs注意，这边有个巨大的坑：此处的basePath在Swagger0.6.5中必须在后面加上api-docs，要不然会报错。
-
因为是权限管理系统，所以很多访问是有权限问题的，为了避免权限问题引发swagger无法正常运行，需在
web.xml中进行如下配置：<servlet-mapping> <servlet-name>dispatcherServlet</servlet-name> <url-pattern>/api-docs/*</url-pattern> </servlet-mapping>到此部为止，已经可以通过json返回API信息了。访问
http://localhost:8088/yourProjName/api-docs会返回类似下面的内容：{"apiVersion":"1.0","apis":[{"path":"/api-docs/api/swagger"}{"path":"/api-docs/r-sys-res-controller"},{"path":"/api-docs/r-user-controller"},{"path":"/api-docs/r-user-role-controller"},{"path":"/api-docs/sch-role-controller"},{"path":"/api-docs/system-controller"}],"basePath":"http://localhost:8088/MedicalMaster/api-docs","swaggerVersion":"1.0"}返回的json是对应的
controller进一步得到相应文档的地址，我们可以在原地址上加上上面的任意一个地址，如：http://localhost:8088/yourProjName/api-docs/api-docs/api/swagger，将得到类似下面的具体json：{"apiVersion":"1.0","apis": [{"description":"","operations":[{"deprecated":false,"httpMethod":"GET","nickname":"queryAPIInfo","notes":"","responseClass":"any","summary":"query api basic information"}],"path":"/api/swagger/info.do"}, {"description":"","operations":[{"deprecated":false,"httpMethod":"GET","nickname":"queryData","notes":"","parameters":[{"allowMultiple":false,"dataType":"String","defaultValue":"","description":"words","name":"words","notes":"","paramType":"query","required":true}],"responseClass":"any","summary":"query data with parameters"}],"path":"/api/swagger/data.do"}], "basePath":"http://localhost:8088/MedicalMaster/api-docs","models":{},"resourcePath":"/api/swagger","swaggerVersion":"1.0"} -
现在，我们来配置图形化界面。图形化界面的原理只是去调用这个json接口，将数据可视化而已。因为此处使用的是
swagger0.6.5所以需要手动添加swagger前端页面。-
首先，从https://github.com/swagger-api/swagger-ui下载最新的swagger-ui，在
webapp下新建swagger目录，将下载下来的项目的dist文件夹下所有的文件拷贝到swagger下。 -
修改
swagger/index.html中的url:原url：url = "http://petstore.swagger.io/v2/swagger.json"; 修改为：url = "http://localhost:8088/yourProjName/";
-
-
重启项目。如果不是权限管理系统的话，那么可以直接访问
http://localhost:8088/yourProjName/swagger/index.html就能看到效果。如果是权限管理系统，那么就先登陆任意账号，然后再访问即可。效果图如下：
遇到的坑
-
因为使用的基于
SpringMVC 3.2.2的durcframework框架开发的权限管理系统，所以首先是无法使用swagger2 和swagger1.x只是用swagger0.6.5。如果使用的是swagger会报无法注入对象的错误，原因是springMVC3和springMVC4的差别。 -
与框架开发分责任交流后，尝试手动更改
durcframework中的springMVC版本,更改后可以使用，但是由于更改的是从maven repository pull下来的文件内的pom.xml，如果是多人协作的话需要自己创建自己的maven repository，太过麻烦。另一个办法是直接更改自己的pom.xml文件，强行覆盖，但是会造成更多奇怪的问题，因为原来的权限管理系统是基于SpringMVC3开发的，会有很多代码层面上的问题。所以最后更改SpringMVC版本的尝试失败，只能够选择低的swagger版本。 -
权限问题是另外一个头疼的问题。因为权限的原因，无法直接访问swagger起的服务，比如
http://localhost:8088/yourProjName/api-docs就直接无法访问，原因是拦截器把它给拦截了。需要在web.xml里面配置拦截器，自动忽略api-docs/*匹配的动作。由于上述问题，直接导致笔者将swagger的调用机制研究了一遍。但是现在的swagger2的配置的确是十分简单，建议能够选择的时候尽量只用最新版本的springMVC。
网友评论