码恋

Swagger

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

应用场景

众所周知，前后端分离开发如今已经成为互联网项目的主要开发方式，并已经被大多数人接受。前后端分离并不是字面意义上的分部门、分团队，一个团队开发前端，一个团队开发后端，而许多项目使用了模板技术，这使得后端在开发过程中不得不参与前端展示的开发，不能做到真正意义上的前后端分离。

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

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

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 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 = “参数具体描述”

运行如下图

❤ 转载请注明本文地址或来源，谢谢合作 ❤