Swagger+Spring+Spring Mvc项目整合DEMO

1.简介

  Swagger是一个简单又强大的能为你的Restful风格的Api生成文档工具，可以自动生成页面形式的Api文档，并且提供测试的功能，Swagger使用起来方便、快捷、降低前后端以及测试的成本，有十分风骚且美观的界面 供测试和查看。

2.缺点

  Swagger嵌入在代码中，依赖强，容易污染代码，大型项目作用性不强（注解太多）若中途使用swagger成本较高。

3.上代码，聊人生

 声明：本文章采用spring+spring mvc+swagger框架，数据方面模拟，其他多余东西没有。

  3.1 创建Maven项目-导入依赖

[plain]  view plain  copy

1. <!-- swagger-mvc -->com.mangofactoryswagger-springmvc1.0.2<!-- swagger-mvc -->javax.servletjavax.servlet-api3.1.0providedjavax.servletjstl1.2com.fasterxml.jackson.corejackson-databind2.6.6org.springframeworkspring-webmvc4.1.6.RELEASEorg.springframeworkspring-web4.1.6.RELEASEorg.springframeworkspring-tx4.1.6.RELEASEorg.springframeworkspring-jdbc4.1.6.RELEASEorg.springframeworkspring-context4.1.6.RELEASEorg.springframeworkspring-context-support4.1.6.RELEASEorg.springframeworkspring-orm4.1.6.RELEASEorg.springframeworkspring-aop4.1.6.RELEASEorg.springframeworkspring-oxm4.1.6.RELEASEorg.springframeworkspring-test4.1.6.RELEASEtest<!-- slfj4 -->org.slf4jslf4j-log4j121.7.7<!-- slfj4 -->  

  3.2 配置spring+spring mvc 

[plain]  view plain  copy

1. <!-- 扫描注解Bean -->  

  3.2 配置web.xml

[plain]  view plain  copy

1. contextConfigLocation  
2.          classpath:spring-config.xml  
3.      org.springframework.web.context.ContextLoaderListenerspringmvcorg.springframework.web.servlet.DispatcherServletcontextConfigLocationclasspath:spring-mvc.xml1springmvc/  

  3.3 Swagger配置信息

[java]  view plain  copy

1. import org.springframework.beans.factory.annotation.Autowired;  
2. import org.springframework.context.annotation.Bean;  
3. import org.springframework.context.annotation.Configuration;  
4. import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;  
5. import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
6. import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;  
7.   
8. import com.mangofactory.swagger.configuration.SpringSwaggerConfig;  
9. import com.mangofactory.swagger.models.dto.ApiInfo;  
10. import com.mangofactory.swagger.paths.SwaggerPathProvider;  
11. import com.mangofactory.swagger.plugin.EnableSwagger;  
12. import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;  
13.   
14. @Configuration  
15. @EnableWebMvc  
16. @EnableSwagger  
17. public class SwaggerPluginConfig extends WebMvcConfigurerAdapter {  
18.   
19.     private SpringSwaggerConfig springSwaggerConfig;  
20.   
21.     @Bean  
22.     public SwaggerSpringMvcPlugin customImplementation() {  
23.         return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  
24.                 .apiInfo(apiInfo())  
25.                 .includePatterns(".*")  
26.                 .useDefaultResponseMessages(false)  
27.                 // .pathProvider(new GtPaths())  
28.                 .apiVersion("0.1")  
29.                 .swaggerGroup("user");  
30.   
31.     }  
32.   
33.     private ApiInfo apiInfo() {  
34.         ApiInfo apiInfo = new ApiInfo("这是标题-Laher", "这是描述-Laher",  
35.                 "服务条款路径", "weisheixiaoxin@qq.com", "Laher博客",  
36.                 "http://blog.csdn.net/weisheixiaoxin");  
37.         return apiInfo;  
38.     }  
39.   
40.     @Override  
41.     public void configureDefaultServletHandling(  
42.             DefaultServletHandlerConfigurer configurer) {  
43.         configurer.enable();  
44.     }  
45.   
46.     class GtPaths extends SwaggerPathProvider {  
47.         @Override  
48.         protected String applicationPath() {  
49.             return "/restapi";  
50.         }  
51.   
52.         @Override  
53.         protected String getDocumentationPath() {  
54.             return "/restapi";  
55.         }  
56.     }  
57.   
58.     @Autowired  
59.     public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {  
60.         this.springSwaggerConfig = springSwaggerConfig;  
61.     }  
62. }  

  3.4 Controller中使用注释声明节点

[java]  view plain  copy

1. //swagger的节点声明，节点名称，类型。  
2. @Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)  
3. @Controller  
4. @RequestMapping("user")  
5. public class UserController  

  3.5 接口方法注释声明

[java]  view plain  copy

1. //swagger的节点声明，节点名称，类型。  
2. @ApiOperation(value = "查询用户", notes = "查询用户信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)  
3. //spring mvc注解声明  
4. @ResponseBody  
5. @RequestMapping(value = "get", method = RequestMethod.GET)  
6. //                          -swagger声明入参变量的英文和是否空         -spring mvc入参声明 这个一定要加  
7. public Result get(@ApiParam(value = "编号", required = true) @RequestParam String id) {  
8.     return new Result(0000, "操作成功", getUser(id));  
9. }  

----后端-配置完成----------------------------------------------------------------------------------   

  3.6.配置前端

声明：前端页面需要使用swagger-ui，所以需要提前下载资源

下载完毕后有一堆的文件，进入   dist 目录下面

拷贝文件：

swagger-ui.min.js

swagger-ui.js

\lib目录

\images目录

\css目录

\index.html页面

拷贝完成后终于快结束了%>_<%。。。打开index.html 配置成自己的路径————ok！！！

----前端-配置完成----------------------------------------------------------------------------------

4.启动项目-案例图

  

打开 /user/get api接口

说明：

id 入参变量名

try it out! 点击测试运行

说明：

  请求路径，响应内容，响应状态码，响应头部信息 信息一目了然。  

  不同的请求、操作、入参、出参、类型等都会有不同的页面格式信息，该demo提供了基本的操作。

5.参考资料

官网： 

  http://swagger.io/

技术支持：

  swagger-ui：https://github.com/swagger-api/swagger-ui

  swagger-core：https://github.com/swagger-api/swagger-core

  swagger-spec：https://github.com/swagger-api/swagger-spec

demo：

   https://github.com/Mozhate/la-swagger.git

---------------------------------------------------------------------------------------------------------