基于SpringMVC 3.22的swagger配置避坑（durcframework）

虽然现在的项目基本都是用最新的版本，但是难免有些老项目还是使用了古老的版本。本文对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的权限管理系统所以碰到了很多坑。废话不多说，配置过程如下：

1. 在pom.xml中添加依赖：

    
    
        com.mangofactory
        swagger-springmvc
        0.6.5
    
   

2. 在springMVC.xml（平时的SpringMVC项目中为xx-sevlet.xml）中添加如下配置：

3. 在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，要不然会报错。

4. 因为是权限管理系统，所以很多访问是有权限问题的，为了避免权限问题引发swagger无法正常运行，需在web.xml中进行如下配置：

    
        dispatcherServlet
        /api-docs/*
    
   

   到此部为止，已经可以通过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"}
   

5. 现在，我们来配置图形化界面。图形化界面的原理只是去调用这个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/";
     

6. 重启项目。如果不是权限管理系统的话，那么可以直接访问http://localhost:8088/yourProjName/swagger/index.html就能看到效果。如果是权限管理系统，那么就先登陆任意账号，然后再访问即可。效果图如下：
   

   
   
   
   

---

遇到的坑

1. 因为使用的基于SpringMVC 3.2.2的durcframework框架开发的权限管理系统，所以首先是无法使用swagger2 和swagger1.x只是用swagger0.6.5。如果使用的是swagger会报无法注入对象的错误，原因是springMVC3和springMVC4的差别。

2. 与框架开发分责任交流后，尝试手动更改durcframework中的springMVC版本,更改后可以使用，但是由于更改的是从maven repository pull下来的文件内的pom.xml，如果是多人协作的话需要自己创建自己的maven repository，太过麻烦。另一个办法是直接更改自己的pom.xml文件，强行覆盖，但是会造成更多奇怪的问题，因为原来的权限管理系统是基于SpringMVC3开发的，会有很多代码层面上的问题。所以最后更改SpringMVC版本的尝试失败，只能够选择低的swagger版本。

3. 权限问题是另外一个头疼的问题。因为权限的原因，无法直接访问swagger起的服务，比如http://localhost:8088/yourProjName/api-docs就直接无法访问，原因是拦截器把它给拦截了。需要在web.xml里面配置拦截器，自动忽略api-docs/*匹配的动作。

   由于上述问题，直接导致笔者将swagger的调用机制研究了一遍。但是现在的swagger2的配置的确是十分简单，建议能够选择的时候尽量只用最新版本的springMVC。