按照现在的趋势，前后端分离几乎已经是业界对开发和部署方式所达成的一种共识。所谓的前后端分离，并不是传统行业中的按部门划分，一部分人只做前端（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 是一个规范和完整的框架，用于生成、描述、调用和可视化 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",
"[email protected]", "MIT License", "/LICENSE");
return apiInfo;
}
}
该swagger作为一个bean被spring所管理
到Swagger UIGithub主页下载
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 = “参数具体描述”
运行如下图
可以在下载项目源码