SpringMVC Swagger UI

Question

按照现在的趋势，前后端分离几乎已经是业界对开发和部署方式所达成的一种共识。所谓的前后端分离，并不是传统行业中的按部门划分，一部分人只做前端（HTML/CSS/JavaScript 等等），另一部分人只做后端（或者叫服务端），因为这种方式是不工作的：比如很多团队采取了后端的模板技术（JSP, FreeMarker, ERB 等等），前端的开发和调试需要一个后台 Web 容器的支持，从而无法将前后端开发和部署做到真正的分离。

通常，前后端分别有着自己的开发流程，构建工具，测试等。做前端的谁也不会想要用 Maven 或者 Gradle 作为构建工具，同样的道理，做后端的谁也不会想要用 Grunt 或者 Gulp 作为构建工具。

前后端仅仅通过接口来协作，这个接口可能是 JSON 格式的 RESTFul 的接口，也可能是 XML 的，重点是后台只负责数据的提供和计算，而完全不处理展现。而前端则负责拿到数据，组织数据并展现的工作。这样结构清晰，关注点分离，前后端会变得相对独立并松耦合。但是这种想法依然还是很理想化，前后端集成往往还是一个很头痛的问题。比如在最后需要集成的时候，我们才发现最开始商量好的数据结构发生了变化，而且这种变化往往是在所难免的，这样就会增加大量的集成时间。

归根结底，还是前端或者后端感知到变化的时间周期太长，不能 及时协商，尽早解决 ，最终导致集中爆发。怎么解决这个问题呢？我们需要提前协商好一些契约，并将这些契约作为可以被测试的中间产品，然后前后端都通过自动化测试来检验这些契约，一旦契约发生变化，测试就会失败。这样，每个失败的测试都会驱动双方再次协商，有效的缩短了反馈周期，并且降低集成风险。具体的实践方式，请参加我同事的一篇博文， 前后端分离了，然后呢？

http://icodeit.org/2015/06/whats-next-after-separate-frontend-and-backend/

不过，仅仅靠纪律是不够的，还需要通过工具的辅助来提高效率。下面，我们就来看一下，一个 API 设计工具——Swagger，将如何帮助我们更好的实现 前后端分离 。

Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

我们在 Gradle 中加入 swagger 的依赖，如果你是 maven 项目，你按照 maven 的方式加入的 denpendency 中

compile 'com.mangofactory:swagger-springmvc:1.0.2'
compile 'com.mangofactory:swagger-models:1.0.2'
compile 'com.wordnik:swagger-annotations:1.3.11'
compile 'com.fasterxml.jackson.core:jackson-core:2.4.4'
compile 'com.fasterxml.jackson.core:jackson-databind:2.4.4'
compile 'com.fasterxml.jackson.core:jackson-annotations:2.4.4'

配置 Swagger

package com.silence.ssm.config;

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;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

/**
 * @author Silence
 * @version 1.0
 * @since JDK 1.8
 */
@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

	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("SSM Project", "Swagger 首页", "developer: Silence",
				"silence940109@gmail.com", "MIT License", "/LICENSE");
		return apiInfo;
	}
}

该 swagger 作为一个 bean 被 spring 所管理

配置 Swagger UI

到 Swagger UI Github 主页下载

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

复制该项目中的 dist 目录下的文件到你的 webapp 根目录下，你也可以专门建立一个文件比如 swagger-ui 来存放这些静态文件

然后在 spring mvc 的配置文件中配置该文件的访问路径

<!-- 配置 swagger-ui 静态页面 -->
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger-ui/"/>

打开 swagger ui 的 index.html ，找到 url = "http://localhost:8080/SSM/api-docs" ，这里改为你的地址

swagger 默认是英文的，你可以加入以下改为中文

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

最后你就可以在 Controller 中加入注解来进行 swagger 的配置

@ApiOperation(value = '接口说明', 
	httpMethod = '接口请求方式', 
	response = '接口返回参数类型', 
	notes = '接口发布说明'；其他参数可参考源码；
@ApiParam(required = '是否必须参数', 
	name = '参数名称', 
	value = '参数具体描述'

运行如下图

可以在 下载 项目源码