前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger
让部署管理和使用功能强大的API从未如此简单。
一、使用介绍
什么是 Swagger?
Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。 
浏览 Swagger-Spec 去了解更多关于Swagger
项目的信息,包括附加的支持其他语言的库。
如何集成Swagger-springmvc到我们的项目中?
依赖:
Maven
<dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>0.9.4</version></dependency>
Gradle
repositories {jcenter()}compile "com.mangofactory:swagger-springmvc:0.9.4"
使用:
要最快捷地启动swagger-springmvc项目并且使用默认设置,推荐的方式是使用SwaggerSpringMvc插件
Spring Java Configuration
@Configuration@EnableWebMvc@EnableSwagger
@ComponentScan("com.myapp.packages")
public class WebAppConfig { ...}
Spring xml Configuration
<mvc:annotation-driven/> 
<!-- Required so swagger-springmvc can access spring's RequestMappingHandlerMapping -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
SwaggerSpringMvcPlugin XML Configuration
为了使用这个插件,你需要创造一个spring Java配置类。使用spring的
@Configuration ,这个配置类必须被定义到你的xml上下文
<!-- Required so swagger-springmvc can access spring's RequestMappingHandlerMapping -->
<mvc:annotation-driven/>
<beanclass="com.yourapp.configuration.MySwaggerConfig"/>
@Configuration@EnableSwagger 
//Loads the spring beans required by the framework
public class MySwaggerConfig {
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. */
@Beanpublic SwaggerSpringMvcPlugin customImplementation(){ 
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).includePatterns(".*pet.*");}}
SwaggerSpringMvcPlugin Spring Java Configuration
使用@EnableSwagger注解 
自动注入SpringSwaggerConfig 
定义一个或多个SwaggerSpringMvcPlugin实例,通过springs @Bean注解
@Configuration@EnableWebMvc
@EnableSwagger
@ComponentScan("com.myapp.controllers")
public class CustomJavaPluginConfig {
private SpringSwaggerConfig springSwaggerConfig;
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfigspringSwaggerConfig{
this.springSwaggerConfig = springSwaggerConfig;
}
@Bean 
//Don't forget the 
@Bean annotationpublic SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*pet.*");
}
private ApiInfo apiInfo() {  
ApiInfo apiInfo = new ApiInfo(  
"My Apps API Title",  
"My Apps API Description",  
"My Apps API terms of service",  
"My Apps API Contact Email",  
"My Apps API Licence Type",  
"My Apps API License URL" );  
return apiInfo;}}
二、碰到的问题
关于@API注解
在Swagger Annotation中: 
API表示一个开放的API,可以通过description简要描述该API的功能。 
在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。 
在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。 
ApiParam用于描述该API操作接受的参数类型
再接着,为项目的Model对象添加Swagger Annotation,这样Swagger Scanner可以获取更多关于Model对象的信息。
@ApiModel(value = "A SayingRepresentation is a representation of greeting")
@JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
public class SayingRepresentation {
private long id;
@ApiModelProperty(value = "greeting content", required = true)
private String content;public SayingRepresentation(long id, String content){this.id
= id;  
this.content = content;
}
public long getId() {  
return id;
}
public String getContent() {  
return content;
}
通过上面的步骤,项目已经具备了提供Swagger格式的API信息的能力,接下来,我们把这些信息和Swagger UI集成,以非常美观,实用的方式把这些API信息展示出来。
和Swagger UI的集成
首先,从github(https://github.com/wordnik/swagger-ui)上下载Swagger-UI,
把该项目dist目录下的内容拷贝到项目的resources的目录assets下。



然后,修改index.html, 把Swagger UI对象中的URL替换为自己的API路径。
window.swaggerUi = new SwaggerUi({ url: "/api/api-docs", dom_id: "swagger-ui-container",
最后,为了能访问到该页面,还需要在Service的Initialize方法中,添加AssetsBundle
public void initialize(Bootstrap<HelloWorldConfiguration> bootstrap) {  
//指定配置文件的名字  
bootstrap.setName("helloWorld");  
bootstrap.addBundle(new AssetsBundle("/assets", "/", "index.html"));}
最后的效果图:
 
三、评价
Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。
Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。
四、参考资料
GitHub:

Spring MVC学习总结(8)——Swagger入门详解的更多相关文章

  1. Spring MVC 学习)——控制器与@RequestMapping详解

    Spring MVC 学习总结(二)——控制器定义与@RequestMapping详解 一.控制器定义 控制器提供访问应用程序的行为,通常通过服务接口定义或注解定义两种方法实现. 控制器解析用户的请求 ...

  2. 转载 Spring、Spring MVC、MyBatis整合文件配置详解

    Spring.Spring MVC.MyBatis整合文件配置详解   使用SSM框架做了几个小项目了,感觉还不错是时候总结一下了.先总结一下SSM整合的文件配置.其实具体的用法最好还是看官方文档. ...

  3. Spring MVC、MyBatis整合文件配置详解

    Spring:http://spring.io/docs MyBatis:http://mybatis.github.io/mybatis-3/ Building a RESTful Web Serv ...

  4. Spring MVC拦截器(Interceptor )详解

    处理器拦截器简介 Spring Web MVC的处理器拦截器(如无特殊说明,下文所说的拦截器即处理器拦截器)类似于Servlet开发中的过滤器Filter,用于对处理器进行预处理和后处理. 常见应用场 ...

  5. spring MVC处理请求过程及配置详解

    本文主要梳理下Spring MVC处理http请求的过程,以及配置servlet及业务application需要的常用标签,及其包含的意义. spring MVC处理请求过程 首先看一个整体图 简单说 ...

  6. Spring框架学习05——AOP相关术语详解

    1.Spring AOP 的基本概述 AOP(Aspect Oriented Programing)面向切面编程,AOP采取横向抽取机制,取代了传统纵向继承体系重复性代码(性能监视.事务管理.安全检查 ...

  7. spring mvc学习(一)入门实例

    springMVC处理流程如下: 通过配置DispacherServlet拦截指定的url,让后经HanddlerMapping来决定调用我自定义的Controller,在Controller中经过业 ...

  8. Spring MVC之@RequestParam @RequestBody @RequestHeader 等详解

    (转自:http://blog.csdn.net/walkerjong/article/details/7946109#) 引言: 接上一篇文章,对@RequestMapping进行地址映射讲解之后, ...

  9. Spring、Spring MVC、MyBatis整合文件配置详解

    原文  http://www.cnblogs.com/wxisme/p/4924561.html 主题 MVC模式MyBatisSpring MVC 使用SSM框架做了几个小项目了,感觉还不错是时候总 ...

随机推荐

  1. 一些常见的iOS面试问题,一眼就能看出 初级和高级工程师的区别

    前言 面试题中有一些一般性的问题,通常是会问到的.面试iOS应聘者时,切入点很重要,不同的切入点会导致不同的结果,没有找到合适的切入点也无法对应聘者有一个全面的了解. 所以下面的面试问题更多的是提供方 ...

  2. Spark之RDD的定义及五大特性

    RDD是分布式内存的一个抽象概念,是一种高度受限的共享内存模型,即RDD是只读的记录分区的集合,能横跨集群所有节点并行计算,是一种基于工作集的应用抽象. RDD底层存储原理:其数据分布存储于多台机器上 ...

  3. (DP)51NOD 1118 机器人走方格

    M * N的方格,一个机器人从左上走到右下,只能向右或向下走.有多少种不同的走法?由于方法数量可能很大,只需要输出Mod 10^9 + 7的结果. Input 第1行,2个数M,N,中间用空格隔开.( ...

  4. 01—Spring基础配置IOC

  5. 转 linux shell自定义函数(定义、返回值、变量作用域)介绍

    linux shell 可以用户定义函数,然后在shell脚本中可以随便调用.下面说说它的定义方法,以及调用需要注意那些事项. 一.定义shell函数(define function) 语法: [ f ...

  6. 【Python精华】100个Python练手小程序

    100个Python练手小程序,学习python的很好的资料,覆盖了python中的每一部分,可以边学习边练习,更容易掌握python. [程序1] 题目:有1.2.3.4个数字,能组成多少个互不相同 ...

  7. 14 C#编程中的逻辑运算

    在C#编程中,我们经常需要处理这些情况. 1. 某种条件为真时,程序这样处理:当某种条件为假时,程序那样处理. 2. 当某种条件为真时,程序一直这样处理: 这里的条件,在C#中就是逻辑运算.接下来我就 ...

  8. C#知识点-GDI绘图

    一.开发环境 编译器:VS2013 .Net版本:4.5 二.开发过程 1.画一条直线 private void btnDrawLine_Click(object sender, EventArgs ...

  9. 在计算机视觉与人工智能领域,顶级会议比SCI更重要(内容转)

    很多领域,SCI是王道,尤其在中国,在教师科研职称评审和学生毕业条件中都对SCI极为重视,而会议则充当了补充者的身份.但是在计算机领域,尤其是人工智能与机器学习领域里,往往研究者们更加青睐于会议 我无 ...

  10. 高性能队列disruptor为什么这么快?

    背景 Disruptor是LMAX开发的一个高性能队列,研发的初衷是解决内存队列的延迟问题(在性能测试中发现竟然与I/O操作处于同样的数量级).基于Disruptor开发的系统单线程能支撑每秒600万 ...