OpenAPI接口的发布，文档，测试----Swagger+Dubbo Rest+Easyrest

最新推荐文章于 2022-08-23 11:17:24 发布

weixin_33907511

最新推荐文章于 2022-08-23 11:17:24 发布

阅读量793

点赞数

文章标签： java ui json

原文链接：https://my.oschina.net/u/3522232/blog/2251291

版权

2019独角兽企业重金招聘Python工程师标准>>>

背景

对外开放的接口，需要清晰的接口文档，方便客户端进行测试，目前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:

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>