基于SpringMVC下的Rest服务框架搭建【1、集成Swagger】

基于SpringMVC下的Rest服务框架搭建【1、集成Swagger】

1、需求背景

SpringMVC本身就可以开发出基于rest风格的服务，通过简单的配置，即可快速开发出一个可供客户端调用的rest服务，通常这些服务要不就是用于手机app的开发，要不就是提供给第三方开发者使用，不管哪种情况，你都需要提供详细的说明给别人，而Swagger就是为这种情况而生的，通过在接口上的注解，生成可供第三方模拟测试和阅读的接口列表，既美观又使用，真是行走江湖之必备良药。
【XmPlatform原创，转载的话请注明】
下面先上美图：

好了，下面言归正传，该如何将Swagger集成到springMVC中呢？

2、依赖包以及Swagger-ui版本

• 如果你用的是maven，依赖包如下：

    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>
<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.0.2</version>
</dependency>
<dependency>
    <groupId>com.wordnik</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.3.11</version>
</dependency>
<!-- swagger-springmvc dependencies -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>15.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.4.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.4.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.4.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml</groupId>
    <artifactId>classmate</artifactId>
    <version>1.1.0</version>
</dependency>

• 如果你用的是jeesite框架的话，你只需引入下面三个lib即可：

swagger-annotations-1.3.11.jar
swagger-models-1.0.2.jar
swagger-springmvc-1.0.2.jar

• Swagger-ui版本

大家可以到https://github.com/swagger-api/swagger-ui/releases下载最新的版本，目前最新版本为2.1.4

3、新建配置Java文件

在你的JavaWeb工程中新建一个名为SwaggerConfig的java文件，代码如下：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * @author xiegx
 * @version 创建时间：2016-8-16 下午2:01:10
 * SwaggerUI配置
 */
@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan(basePackages ={"com.xxx.soa"})
public class SwaggerConfig extends WebMvcConfigurerAdapter {  

    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(".*")
                .swaggerGroup("XmPlatform")
                .apiVersion("1.0.0");
    }

    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
      configurer.enable();
    }
    /*
	 * "标题 title",
	 * "描述 description",
	 * "termsOfServiceUrl",
	 * "联系邮箱 contact email",
	 * "许可证的类型 license type",
	 * "许可证的链接 license url"
	 */
    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "xxx平台API文档",
                "后台RESTful API",
                "",//
                "admin@xmplatform.com",
                "",
                "");
        return apiInfo;
    }
}

注意：basePackages为扫描的包路径(你的controller所在的包路径)，其他的东西大家看看应该就懂的了，就不多说了。

4、新建测试Controller

例如新建一个TestController.java，代码如下：

@Controller
@RequestMapping(value = "/soa/test")
@Api(value="TestController",description="测试接口描述")
public class TestController {
	/*
	 * @ApiOperation(value = "接口说明", httpMethod ="接口请求方式", response ="接口返回参数类型", notes ="接口发布说明"
	 *
	 * @ApiParam(required = "是否必须参数", name ="参数名称", value ="参数具体描述"
	 */
	@RequestMapping(value = {""})
	@ApiOperation(value="接口说明(测试)",httpMethod="GET",notes="在没有会话、没有签名的情况下，进入方法体")
	public void test(HttpServletRequest request, HttpServletResponse response, Model model) {
		try {
			response.getWriter().write("ignoreAll");
		} catch (IOException e) {
			e.printStackTrace();
		}
	}
}

上述代码中的几个注解需要说明一下：

• Api
  表明可供Swagger展示的接口类，value表示接口类的描述（Controller类的这个注解可加可不加，加这个注解更多的是为了显示接口类的描述）
• ApiOperation
  表明这个方法供Swagger展示的接口方法，value等含义详细可看上述代码中的注释
• ApiParam
  方法中的参数只有加了这个注解，才能显示中文描述，否则只显示英文

5、静态资源文件的配置

将步骤2、中提到的最新版本的Swagger-ui拷贝到你的JavaWeb工程中

假如你用的是jeesite框架，你可以拷贝到static目录下，例如static\swagger；你也可以拷贝到WEB-INF目录下，例如WEB-INF\swagger,不过此时你需要在springMVC配置文件中进行静态文件过滤的处理，例如<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

6、收工，启动应用服务器

打开浏览器，访问swagger目录中的index.html，即可看到美观的接口文档呈现在你面前。

You Want More ？Ok，That is it

1、如何汉化/显示中文

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> -->

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

大家可能会问，Content Type是application/json有什么影响，为什么要修改为其他呢？这里就要涉及到springMVC中将请求传递过来的参数注入到Controller方法对应对象的原理了，具体知识大家可以搜索一下，这个不是本文重点我就不多讲了，其实我们通常写的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了

3、想要知道ApiOperation注解中httpMethod等参数都能写哪些值？

这个看api文档吧，提供一个地址给大家：http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html

---

还有更多问题？欢迎留言讨论。