OpenAPI接口的發佈，文檔，測試----Swagger+Dubbo Rest+Easyrest

背景

對外開放的接口，須要清晰的接口文檔，方便客戶端進行測試，目前restful風格的接口定義是最好理解，調用和測試的接口風格；服務提供端也須要一種簡單的辦法，把已有的服務接口發佈爲restful風格，代碼註釋便可做爲接口文檔，是服務端程序員可接受的方式，快捷，方便。

解決方案

首先選擇restful風格的web接口，而不是soap或者wsdl風格的web服務接口，優勢不少，java6已經把jax-rs做爲標準的一部分。

 

dubbo做爲一種十分流行和強大的微服務框架，支持rest風格的rpc協議，dubbo官方框架2.6.0版本整合了dubbox的rest協議代碼，使用dubbo rest協議很方便把咱們寫的業務邏輯代碼（spring bean風格的接口實現）發佈成restful服務接口。

dubbo rest rpc協議基於easyrest實現restful rpc；easyrest是JAX-RS一種實現，目前是3.0.7版本，支持JAX-RS2，經過jcp認證。

 

Swagger是一種Openapi接口定義，文檔化，展現，測試的解決方案，由swagger core, swagger annotation, swagger module, swagger ui, swagger editor等組件組成。目前是openapi最爲完整解決方案。

 

項目如何整合

服務端工做

定義接口上面的rest風格註解和swagger開放接口說明

如何定義restful接口，網上文檔較多，這裏不具體展開，示例：

@Api(value = "/order", description = "IOrderServiceApi Resource", produces = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON)
@Path("/order")
@Consumes({ "application/json" })
@Produces({ "application/json" })
@Service("orderServiceApiImpl")
public class OrderServiceApiImpl implements IOrderServiceApi {

@Resource
private IOrderService orderService;

@Resource
private IMerchantInfo merchantInfo;

@Path("/create")
@POST
@Override
public void create(Order order) {
orderService.createOrder(order);
}

@Path("/get/{userId}/{orderId}")
@GET
@ApiOperation(value = "獲取一個訂單", notes = "返回一個訂單", response = Order.class)
@Override
public Order getOrder(
@ApiParam(value = "用戶id", allowableValues = "range[1,10000000000]", required = true) @PathParam("userId") String userId,
@ApiParam(value = "訂單流水id", allowableValues = "range[1,10000000000]", required = true) @PathParam("orderId") String orderId) {
// hessian rpc測試
try {
 

return orderService.getOrder(userId, orderId);
}

}

發佈接口爲rest風格協議

具體如何發佈dubbo協議，不在此文介紹，能夠參考微服務開發指南這篇文章。這裏重點介紹如何定義rest協議：

<dubbo:protocol name="rest" server="jetty" extension="io.swagger.jaxrs.listing.SwaggerSerializers,com.yspay.framework.rest.easyrest.OriginAccessSettingFilter" host="10.211.61.58" port="8891" threads="10"/>

這裏有個屬性extension，都是對swagger的功能支持，是給easyrest使用的。

有了rest協議定義以後，把發佈的服務加上rest協議便可

<dubbo:service interface="com.yspay.sample.dubboprovider.api.IOrderServiceApi" ref="orderServiceApiImpl"
protocol="hessian3,rest" validation="false"></dubbo:service>

 

定義swagger的openapi掃描包範圍

告訴swagger，要把項目中哪些接口做爲openapi發佈出去，在spring 任何一個配置文件裏面定義下面這個bean:

<bean id="swaggerConfig" class="io.swagger.jaxrs.config.BeanConfig">
<property name="title" value="Swagger 整合dubbo例子服務提供端應用"/>
<property name="version" value="1.0.0" />
<property name="schemes" value="http" />
<property name="resourcePackage" value="com.yspay.sample.dubboprovider.api"/>
<property name="scan" value="true"/>
<property name="prettyPrint" value="true"/>
</bean>

resourcePackage屬性定義開放接口所在的包

 

定義swagger對外發布接口定義的接口

在spring 配置文件裏面定義：

<dubbo:service interface="com.yspay.framework.rest.swagger.IApiListingResourceService" ref="apiListingResource"
protocol="rest" validation="false"></dubbo:service>

<bean id="apiListingResource" class="com.yspay.framework.rest.swagger.ApiListingResourceServiceImpl"/>
這個接口是restful風格的dubbo接口，能夠經過訪問dubo restful接口同樣的方式獲取到對外接口的定義，swagger ui上面指定這個路徑便可訪問這個項目裏面的全部接口定義，一般路徑是http://10.211.61.58:8890/swagger.json

 

 

部署Swagger UI

swagger ui是一個純html+js+css項目，靜態web項目，隨意部署在一種web容器中便可；

 

 

客戶端工做

設置客戶端訪問協議爲rest

有了上面服務端發佈的服務，客戶端只須要在接口上面指定是rest協議訪問方式便可：
<dubbo:reference id="orderServiceClient" protocol="rest" interface="com.yspay.sample.dubboprovider.api.IOrderServiceApi"></dubbo:reference>

在swagger ui上面進行查看接口和測試

在swagger ui部署提供的url訪問界面，把每一個應用的獲取swagger接口定義的url輸入到界面上面的輸入框，而後點擊explore就能夠出現這個應用的全部接口，點擊接口進去，可看到接口的參數定義，而後能夠輸入參數進行測試。接口調用結果會顯示在下面，馬上體驗一下吧！