swagger 是一个可视化RESTful WebService的工具。
官网：http://swagger.io
效果
下图可以看出，swagger清晰地展现了web服务的方法、地址、发送json格式与应答json格式。还可以通过它直接进行服务调用，查看结果。
图1 swagger的效果
工作原理
视图部分： swagger-ui是一系列css\js资源，它通过html页面向用户展示一个应用的RESTful API信息。它通过向swagger-core后台模块发送ajax请求获取必要的信息。
其实就是一个json，我们可以截取一点来看看：
//swagger.json 示例
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": ""
},
"host": "localhost:8080",
"basePath": "/webService",
"tags": [{
"name": "hello"
}],
"schemes": ["http"],
"paths": {
"/helloworld": {
"get": {
"tags": ["hello"],
"operationId": "wsHello",
"parameters": [],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "string"
},
"headers": {
}
}
}
}
}
}
}
后台部分：swagger-core通过 io.swagger.annotations.Api等注解感知到我们的API信息，从而以json格式应答web页面的ajax请求。
服务器部分：可以在tomcat中用。
与jersey集成部署
jersey在tomcat中的配置太灵活了，可以写在web.xml中作servlet，也可以作filter，还可以在java代码中继承某个类，更可以继承相关的其他类！以下是我试验成功的一种情况。
1.Adding the dependencies to your application<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.0</version>
</dependency>
2.Hooking up Swagger-Core in your Application
即让jersey感知到swagger的存在。
public class App extends ResourceConfig {
public App() {
// 向jersey框架注册资源类，凡完全限定名是以指定字符串开头的类，都将包含
packages("com.likeyichu.webservice.resource");
register(JacksonFeature.class);
//swagger
Set<Class<?>> resources = new HashSet<>();
resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
registerClasses(resources);
}
}
3.Configure and Initialize Swagger
添加servlet即可，主要是为了配置我们api的地址，因为swagger可以发送请求的。
<servlet>
<servlet-name>Jersey2Config</servlet-name>
<servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
<init-param>
<param-name>api.version</param-name>
<param-value>1.0.0</param-value>
</init-param>
<init-param>
<param-name>swagger.api.basepath</param-name>
<param-value>http://localhost:8080/webService/api</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
配置完成，即可在浏览器地址栏中输入webservice目录\swagger.json进行验证。
4.前端资源
github上的swaggerUI项目就是，下载下来就好。注意要改index.html，里面swagger.json的地址指向自己的就好。
常见异常
现象：无穷递归早成栈溢出。
代码：
@Api(value="swagger test")
@Path("book")
@JsonAutoDetect
@JsonPropertyOrder(value = {"price", "name"})
@JsonIgnoreProperties(value = {"year"})
public class Book {
@JsonProperty("name1")
public String name = "Physics";
public String price = "123";
public String year = "2015";
@GET
@Produces(MediaType.APPLICATION_JSON)
public Book wsBook(){
return new Book();
}
}
原因：swagger在进行资源扫描的时候有以下步骤：
1.因为@Api注解找到了Book类；
2.发现了类下的wsBook()这个函数，它的返回值是Book对象，于是查看它的类有没有@Api注解。发现有，转入步骤1。
于是就造成了无穷递归。
解决办法是资源类不当做Pojo用。
