spring mvc swagger ui构建restful接口

Author: scalad

swagger/README.md

@@ -0,0 +1,113 @@
+###SpringMVC Swagger Swagger UI
+
+按照现在的趋势，前后端分离几乎已经是业界对开发和部署方式所达成的一种共识。所谓的前后端分离，并不是传统行业中的按部门划分，一部分人只做前端（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",
+					"[email protected]", "MIT License", "/LICENSE");
+			return apiInfo;
+		}
+	}
+
+该swagger作为一个bean被spring所管理
+
+
+####配置Swagger UI
+
+到[Swagger UI](https://github.com/swagger-api/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 = “参数具体描述”
+
+运行如下图
+
+![](https://github.com/silence940109/Java/blob/master/swagger/image/index.png)
+
+可以在[下载](https://github.com/silence940109/SSM/releases/tag/1.2)项目源码