点点滴滴在学习

在jersey中集成swagger

原文： swagger (可视化RESTful API的工具)

wagger 是一个可视化RESTful WebService的工具。

官网：http://swagger.io

效果

下图可以看出，swagger清晰地展现了web服务的方法、地址、发送json格式与应答json格式。还可以通过它直接进行服务调用，查看结果。

图1 swagger的效果

工作原理

视图部分： swagger-ui是一系列css\js资源，它通过html页面向用户展示一个应用的RESTful API信息。它通过向swagger-core后台模块发送ajax请求获取必要的信息。

其实就是一个json，我们可以截取一点来看看：

 

[javascript] view plain copy
 
  1. //swagger.json 示例  
  2. {  
  3.     "swagger": "2.0",  
  4.     "info": {  
  5.         "version": "1.0.0",  
  6.         "title": ""  
  7.     },  
  8.     "host": "localhost:8080",  
  9.     "basePath": "/webService",  
  10.     "tags": [{  
  11.         "name": "hello"  
  12.     }],  
  13.     "schemes": ["http"],  
  14.     "paths": {  
  15.         "/helloworld": {  
  16.             "get": {  
  17.                 "tags": ["hello"],  
  18.                 "operationId": "wsHello",  
  19.                 "parameters": [],  
  20.                 "responses": {  
  21.                     "200": {  
  22.                         "description": "successful operation",  
  23.                         "schema": {  
  24.                             "type": "string"  
  25.                         },  
  26.                         "headers": {  
  27.                               
  28.                         }  
  29.                     }  
  30.                 }  
  31.             }  
  32.         }  
  33.     }  
  34. }  



 

后台部分：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
[html] view plain copy
 
  1. <dependency>  
  2.     <groupId>io.swagger</groupId>  
  3.     <artifactId>swagger-jersey2-jaxrs</artifactId>  
  4.     <version>1.5.0</version>  
  5. </dependency>  
2.Hooking up Swagger-Core in your Application
即让jersey感知到swagger的存在。
[java] view plain copy
 
  1. public class App extends ResourceConfig {  
  2.     public App() {  
  3.         // 向jersey框架注册资源类，凡完全限定名是以指定字符串开头的类，都将包含  
  4.         packages("com.likeyichu.webservice.resource");  
  5.         register(JacksonFeature.class);  
  6.         //swagger  
  7.         Set<Class<?>> resources = new HashSet<>();  
  8.         resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);  
  9.         resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);  
  10.         registerClasses(resources);  
  11.     }  
  12. }  
3.Configure and Initialize Swagger

添加servlet即可，主要是为了配置我们api的地址，因为swagger可以发送请求的。

 

[html] view plain copy
 
  1. <servlet>  
  2.       <servlet-name>Jersey2Config</servlet-name>  
  3.       <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>  
  4.       <init-param>  
  5.           <param-name>api.version</param-name>  
  6.           <param-value>1.0.0</param-value>  
  7.       </init-param>  
  8.       <init-param>  
  9.           <param-name>swagger.api.basepath</param-name>  
  10.           <param-value>http://localhost:8080/webService/api</param-value>  
  11.       </init-param>  
  12.       <load-on-startup>2</load-on-startup>  
  13.   </servlet>  

配置完成，即可在浏览器地址栏中输入webservice目录\swagger.json进行验证。

4.前端资源

github上的swaggerUI项目就是，下载下来就好。注意要改index.html，里面swagger.json的地址指向自己的就好。

常见异常

微笑现象：无穷递归早成栈溢出。
代码：
[java] view plain copy
 
  1. @Api(value="swagger test")  
  2. @Path("book")  
  3. @JsonAutoDetect  
  4. @JsonPropertyOrder(value = {"price", "name"})  
  5. @JsonIgnoreProperties(value = {"year"})  
  6. public class Book {  
  7.     @JsonProperty("name1")  
  8.     public String name = "Physics";  
  9.     public String price = "123";  
  10.     public String year = "2015";  
  11.     @GET  
  12.     @Produces(MediaType.APPLICATION_JSON)  
  13.     public Book wsBook(){  
  14.         return new Book();  
  15.     }  
  16. }  
 
微笑原因：swagger在进行资源扫描的时候有以下步骤：
1.因为@Api注解找到了Book类；
2.发现了类下的wsBook()这个函数，它的返回值是Book对象，于是查看它的类有没有@Api注解。发现有，转入步骤1。
于是就造成了无穷递归。
解决办法是资源类不当做Pojo用。

导航