SpringMVC与Swagger整合

项目中要使用Swagger，如是对它进行了学习，并成功将其与SpringMvc进行整合。下面就如何将Swagger与SpringMVC项目进行整合做详细说明，方便以后查阅：

步骤一：

引入需要使用到的jar包：

       <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.9.5</version>
        </dependency>

        <dependency>
              <groupId>com.fasterxml.jackson.core</groupId>
              <artifactId>jackson-core</artifactId>
             <version>2.8.1</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.8.1</version>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.8.1</version>
        </dependency>
        
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>20.0</version>
        </dependency>

步骤二：

添加自定义的swagger配置文件：

package com.test.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * @author Administrator
 * Swagger配置
 */
public class MySwaggerConfig {
    
    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig){
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");
    }

    private ApiInfo apiInfo(){
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

步骤三：

将以下2行配置信息加入到springMvc.xml配置文件：

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

<bean class="com.test.config.MySwaggerConfig" />

步骤四：

在代码中添加相关信息配置（说明：代码中可以不做任何配置也可以正常测试，即此步骤可以忽略）

    @ResponseBody
    @RequestMapping(value = "test", method = RequestMethod.POST, produces = "application/json; charset=utf-8")
    @ApiOperation(value = "测试", httpMethod = "POST", response = String .class, notes = "测试")
    public String test(@ApiParam(required = true, name = "data", value = "测试json数据") @RequestParam(
            value = "data") String data, HttpServletRequest request)
    {
        return "test";
     }

说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

步骤五：

添加Swagger UI配置：

1）从github下载swagger UI：

https://github.com/swagger-api/swagger-ui

2）解压缩，将dist下所有内容拷贝到本地项目webapp下面：

步骤六：

将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json修改为http://localhost:port/{projectname}/api-docs

步骤七：

打开swagger-ui.js文件，找到以下内容：

this.consumes = args.consumes || parent.consumes || ['application/json'];

将其修改为以下内容：

this.consumes = ['application/x-www-form-urlencoded','application/json'];

说明：1、默认只支持application/json参数类型，上面修改使前端支持application/x-www-form-urlencoded和application/json两种参数类型；

            2、如果不做上述修改，前端要支持application/x-www-form-urlencoded参数类型，解决方法见下面问题3；

完成上述配置后，则swagger与springMvc整合结束，现在可以启动你的项目。

访问http://localhost:port/{projectName}/index.html即可看到成功页面：

访问说明：

1、参数类型为：application/x-www-form-urlencoded

      body传参格式示例：pageName=测试&pageId=11

2、参数类型为：application/json

      body传参格式示例：

       {
            "pageName":"测试",
            "pageId":"11"
       }

常见问题：

访问http://localhost:port/{projectName}/index.html可能出现的问题：

1）Can't read from server. It may not have the appropriate access-control-origin settings.

原因：可能因为浏览器中输入的ip地址与index.xml文件中配置的url地址不一致导致

解决：将2个地方的地址保持一致即可。如都为localhost

2）如何汉化/显示中文

解决：

swagger-ui本身是支持多语言的，在index.html中有这么一段代码：

<!-- Some basic translations -->
  <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
  <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
  <!-- <script src='lang/en.js' type='text/javascript'></script> -->

大家只需要把注释打开，同时加入对应的中文js即可，最终修改如下：

<!-- Some basic translations -->
  <script src='lang/translator.js' type='text/javascript'></script>
  <script src='lang/zh-cn.js' type='text/javascript'></script>
  <!-- <script src='lang/en.js' type='text/javascript'></script> -->

3） 在swagger-ui中默认的参数的Content Type是application/json，测试时发现后台参数没有接收到值，怎么办？

原因：我们通常写的Controller方法，默认的Content Type其实是application/x-www-form-urlencoded，而swagger中参数的默认Content Type是application/json，这样就会导致使用swagger测试时，提交到Controller方法的对应参数无法正确注入。那么，该如何处理呢，能改成其他吗？其实在swagger-ui的Issues中有人提到过，https://github.com/swagger-api/swagger-ui/issues/658，解决的办法就是要设置consumes这个东东。解决办法找到了，那consumes在哪里设置呢？

解决：在@ApiOperation这个注解里面进行设置，将consumes修改为“application/x-www-form-urlencoded”即可，例如：

@ApiOperation(value="接口说明(测试)",httpMethod="GET",consumes="application/x-www-form-urlencoded",notes="在没有会话、没有签名的情况下，进入方法体")

那在什么情况下，参数的Content Type才是application/json呢？

当你的参数加了@RequestBody注解的时候，表示此参数接收的是json数据，这个时候你就可以将consumes写为application/json了

4）将接口测试文档导出为PDF文档？

解决：点击“展开操作”节点，然后浏览器中点击打印功能，选择为PDF保存即可。