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就能够出现这个应用的全部接口，点击接口进去，可看到接口的参数定义，而后能够输入参数进行测试。接口调用结果会显示在下面，马上体验一下吧！