CN105278946B - 一种RESTful API可视化方法 - Google Patents

Abstract

本发明公开了一种API可视化的方法。API可视化，使得API更加直观和易懂，并且开发者可以定义和修改成所需的API结构，重新发布自己API服务，以供其他开发者使用。本发明可以支持程序读取API描述文件，程序根据描述文件自动传递参数，简化了API开发者的工作，API结构更加直观和易读，更加容易被非专业的开发者接受。本发明中的自动生成API输出结构，可有效地减少了开发者设计API输出结构的工作，使得整个API结构可以半自动化生成。

Description

一种RESTful API可视化方法

技术领域

本发明涉及服务计算领域，服务组合基于RESTful架构的技术领域，具体涉及一种RESTful API可视化方法。

背景技术

现有很多对外提供服务的网站，如百度API store、聚合数据、API Cloud、leanCloud等等，这些服务提供商的网站都是基于RESTful架构。从Web开发技术的发展过程来看，Web从最初的主要支持静态页面，到后来越来越支持动态页面。静态页面为主典型代表有门户网站、电子商务网站、搜索引擎、社交网站，到后来交互性强的多人在线的网页游戏。Rest是Roy Fielding在他2000年的博士学位论文中提出的一种新的网站架构。REST本意是“Representational State Transfer”，意思是表述性转移的缩写。所有网站符合REST设计风格都称为RESTful。分布式应用架构是REST非常成功的例子。

REST风格中有以下六个关键词：

1.资源（Resource）

资源是一种对服务器抽象的概念。将服务器看成由很多离散的资源组成，每个资源是服务器上一个可命名的抽象概念。一个资源可以由特定url来表示，客户端可以通过url来访问对应资源。

2.资源表述

资源表述表示某个资源某段时间内的状态表述。主要用于服务器和客户端进行数据交换。资源的表述可以有多种方式，以下几个比较常见的，如HTML/XML/JSON/TXT/PNG等等。

3.状态转移

指客户端与服务器端之间转移代表资源状态表述。客户端以HTTP方式请求服务器上的资源，对资源进行操作，比如添加资源、修改资源、删除资源。

4.统一接口

客户端通过HTTP协议来访问服务器。正好HTTP的几个方法对应服务器资源的操作，GET方法表示获取资源，POST方法表示新建资源，DELETE方法表示删除资源，PUT表示更新资源。

5.超文本驱动

超文本驱动的全称为“将超媒体作为应用状态的引擎”。将Web应用看成一个很多状态组成的状态机。在应用中，不仅包含资源，还包含对资源操作的状态转移语义。

基于RESTful架构的网站，其对外提供的服务，可以统称为RESTfulAPI。下文出现API都是指的RESTful API。RESTful架构通常是，客户端以HTTP或HTTPS方式对服务器发起请求，服务器返回数据格式一般是JSON类型。开发者通过阅读相关的文档来使用API。但是每个服务提供商的API文档格式千奇百怪，有些文档并不够完善。甚至有时候API已经改变了，但没有及时更新文档也是常见问题。文档作为开发者唯一交流方式有很多弊端，并且不够直观易懂。

发明内容

针对上述的遇到的问题，本发明了一种RESTful API可视化方法，使API更加直观并且易懂。本发明基于API调用实例的返回数据，可视化展示API。

具体的，本发明的采用了如下技术方案：

一种RESTful API可视化方法，基于API调用实例的返回数据，可视化展示API，具体包括如下步骤：

1、分析API的输入结构和具体用途，构造输入用例；

2、执行步骤1中所述输入用例，得到返回数据，所述返回数据包括如下两类：

a.服务器返回有效数据；

b.服务器返回无效数据；

3、若步骤2中返回的是无效数据，提示返回无效数据；若返回的是有效数据，则解析有效数据，将其转化为模型数据；

4、使用自动布局算法，将所述模型数据按照算法可视化展现。

优选的，所述步骤1中构造输入用例具体包括如下步骤：

1.1 根据需求，设计API节点基本信息；

1.2 根据所述API节点基本信息，设计API输入结构；

1.3 根据所述API输入结构，构造合理的输入用例。

优选的，所述步骤4具体包括如下步骤：

4.1定义ApiModel数据模型，用于描述API的功能用途及其它基本信息；

定义InputModel数据模型，用于表示API的输入结构根节点；

定义OutputModel数据模型，用于表示API的输出结构根节点；

4.2 将所述InputModel、ApiModel、OutputModel按照从左到右的顺序，即横坐标从小变大，但纵坐标相等的顺序摆放；

4.3递归生成InputModel子树所有子模型坐标；从右向左顺序摆放元素，每个子节点与父节点的坐标差值为常量（-dx,dy）；

4.4递归生成OutputModel子树所有子模型坐标；从左到右顺序摆放元素，每个子节点与父节点坐标差值为常量(dx,dy)。

本发明的有益技术效果在于：

（1）直观地将API的内部数据结构展现出来，利于开发者快速读懂API。比阅读API文档，更加的快速和直观。

（2）只需要人工设计API的输入结构和输入数据示例，即可获得API的输出。一般API的输出结构比较复杂，该方法可以减少手动设计API的工作量。

（3）可视化展现API结构，人工辅助给每个节点，添加一些描述信息，最后可以自动生成统一格式的文档。

附图说明

图1为本发明一个实施例的实现框架示意图；

图2为本发明一个实施例火车票到站查询的示例图。

具体实施方式

为了更加具体描述本发明，下面结合附图及具体实施方式对本发明的技术方案详细说明。

为了可视化的图形显示API结构，本发明定义了一种资源模型，即将整个API看成一个树状结构，节点表示数据字段（字段对应值对类型的数据），而连线表示字段之间的包含关系，如果节点有子节点，那么子节点表示的数据字段为父节点的内部字段。API节点表示根节点，其子节点有输入和输出。

本发明的一种RESTful API可视化方法，包括如下步骤：

（1）分析API的输入结构和用途，构造合理的输入用例；

（2）执行（1）输入用例，获得返回数据，返回数据分两类：

ⅰ服务器返回正常的有效数据；

ⅱ服务未返回有效的数据；

（3）若返回的是有效数据，则解析（2）返回数据，将其转化为模型数据；若返回的是无效数据，则提示返回无效数据

在本发明的一个实施例中，为了实现上述步骤(2)中，将JSON数据对应成内存中的模型数据，本实施例定义了KeyValueModel来对应JSON的值对，定义了连线模型LineConnectionModel表示JSON字段的内部字段包含关系。定义了ApiModel模型数据，用来描述API的功能用途等基本信息，InputModel数据模型表示API的输入结构根节点，OutputModel数据模型表示API的输出结构根节点，连线模型用于表示模型数据节点之间的包含关系。本文使用了MVC设计模式,可以直接模型Model映射成视图View,通过控制器Controller来管理Model与View之间的联系。当用户操作视图时，Controller可以将用户输入数据转化为对应的模型数据。当模型改变时，Controller将响应模型对应视图View的变化。

上述步骤（2）中，对返回结果1的处理具体过程如下：

以下方法使用到第三方JSON解析开源工具JSON-lib。将整个JSON的作为一个输出的根节点，使用迭代器方法深度优先遍历整个JSON数据结构。假设当前迭代器指向的节点是p, Kv(key,value)是p的某一个内部字段。Kv的value有一下几种类型：

a. 如果value是基本数据类型，如int、double、string。则p对应生成一个KeyValueModel类型的模型，作为模型的叶子节点。将key值作为模型的信息值保存在KeyValueModel。

b. 如果value是JSONObject类型，则p对应生成KeyValueModel,同时继续深度优先遍历其孩子child节点。同时生成一个LineConnectionModel，连线模型的起点是p，终点是当前孩子child节点的模型，用于表示数据字段对应模型之间包含的逻辑关系。

c. 如果value是JSONArray类型，则p对应生成KeyValueModel模型。因为数组中的元素结构都是一致的。如果value中至少有一个元素，只需要取数组的第一个元素作为p的孩子child节点。深度优先遍历孩子节点。最后p的每个孩子对应生成一个LineConnectionModel，连接的起点是p，终点是child节点对应的模型。

对步骤（2）中的2结果，服务器返回无效数据。属于异常处理范围，提示异常信息即可。

（4）对模型使用自动布局算法。即自动生成模型数据的坐标信息数据，以便可视化的展现。自动布局算法步骤如下：

1. 从左到右的摆放模型节点，左边是InputModel输入节点子树，中间是ApiModel模型根节点，右边是OutputModel输出模型节点子树。以上三个模型横坐标从小到大递增的顺序，保证模型视图不会相互覆盖即可，它们纵坐标相等。为了使模型数据自动化布局。约定父节点与子节点横纵坐标差值为常量（dx,dy）。

2. 递归计算InputModel子树的所有模型的坐标信息。因为已确定InputModel的坐标信息，因此子树中的模型节点按照从右到左顺序摆放。模型保存与其相连的所有连线模型数据，以InputModel作为根节点,深度优先遍历。假设遍历的模型节点是p：

l 若p为叶子节点，则设置p为起点坐标(x,y)。

l 若p不是叶子节点，则深度优先遍历其孩子模型节点。直到p的所有的孩子节点的坐标都已经计算，再将p的纵坐标设置成所有孩子节点纵坐标平均值，因为p所有的孩子节点横坐标都相等，那么p的横坐标为孩子节点横坐标减去dx。这样就求出了节点p的坐标。

3. 递归计算OutputModel子树的所有模型的坐标信息。具体方法可参考以上2。不一样的是OutputModel子树中的模型节点按照从左到右的顺序摆放。再已经递归计算出来节点p的所有孩子坐标信息，之后，p的横坐标加dx即可。而p的纵坐标计算方法与2中的计算方法一致。

最终Controller通过Model的模型数据将View展现。

基于本发明的上述技术方案，在本发明进一步的实施例中，开发了一套RESTfulAPI可视化工具，取名为OkApiDesigner API设计器。利用工具可以定义API的基本信息，功能，API输入结构，API输出结构。如图1所示，OkAPIDesigner的具体实现如下：

（1）以Eclipse RCP技术为基础，实现OkAPIDesigner的界面框架，包括属性视图和大纲视图，编辑视图等，以及编辑API需要地一些快捷键、工具栏和菜单工具；

（2）以GEF作为底层框架，设计实现“API”,“API输入”，“API输出”，“连接”等可视化的模型元素，并负责响应相关模型数据的、与相关视图的进行交互；

（3）以JSONlib作为API描述文件管理的主要框架，设计实现“保存”和“打开”等API描述文件管理的操作。

如图2所示，本实施例中API实例是火车票站到站查询API结构。具体的实施方法如下：

（1）设计API根节点，通过编辑器的模型组件中找到API模型，拖拽到编辑区，然后在属性视图界面编辑输入API模型的基本信息。

（2）设计API的输入部分，选择模型组件中的Input模型，拖拽至编辑区，在属性视图界面编辑其基本信息，在模型组件中找到连线模型，选择连线之后，分别选择编辑区的Input模型节点和API模型节点作为连线的两个端点，将其连接，表示模型的包含关系。将每一个输入参数当成KeyvalueModel模型，将其拖拽到编辑区，在属性视图编辑其属性，再选择连线，连接Input节点和KeyvalueModel节点。同理，每一个输入参数模型都是同样生成，这里就不再一一赘述。

（3）按照已经设计好的API输入结构，根据每个字段描述信息，设计合理的API输入实例数据，程序通过输入参数执行该API实例。得到API的返回数据，再按照上述的解析数据的算法，获得API输出结构模型数据，最后再与（2）中的模型数据合并，产生一个完整的API数据模型，再可视化展现API。图2即为实例可视化最终展示效果。

最后申明，以上实施例仅作说明使用，本领域的人员应当理解，只要不脱离本发明的精神和范围的任何修改或者局部替换，依然可以参考发明进行修改与合理替换。

Claims (2)

1.一种RESTful API可视化方法，基于API调用实例的返回数据，可视化展示API，具体包括如下步骤：

1、分析API的输入结构和具体用途，构造输入用例；

2、执行步骤1中所述输入用例，得到返回数据，所述返回数据包括如下两类：

a.服务器返回有效数据；

b.服务器返回无效数据；

3、若步骤2中返回的是无效数据，提示返回无效数据；若返回的是有效数据，则解析有效数据，将其转化为模型数据；

4、使用自动布局算法，将所述模型数据按照算法可视化展现，具体包括如下步骤：

4.1定义ApiModel数据模型，用于描述API的功能用途及其它基本信息；

定义InputModel数据模型，用于表示API的输入结构根节点；

定义OutputModel数据模型，用于表示API的输出结构根节点；

4.2将所述InputModel、ApiModel、OutputModel按照从左到右的顺序，即横坐标从小变大，但纵坐标相等的顺序摆放；

4.3递归生成InputModel子树所有子模型坐标；从右向左顺序摆放元素，每个子节点与父节点的坐标差值为常量(-dx,dy)；

4.4递归生成OutputModel子树所有子模型坐标；从左到右顺序摆放元素，每个子节点与父节点坐标差值为常量(dx,dy)。

2.根据权利要求1所述的RESTful API可视化方法，其特征在于：所述步骤1中构造输入用例具体包括如下步骤：

1.1根据需求，设计API节点基本信息；

1.2根据所述API节点基本信息，设计API输入结构；

1.3根据所述API输入结构，构造合理的输入用例。