发明内容
基于此,有必要针对上述问题,提供一种服务接口文档和在线测试工具生成方法、装置,实现服务接口文档和在线测试工具的自动生成。
一种服务接口文档生成方法,包括步骤:
定义包含文档信息的服务接口信息,生成服务接口文件;
对所述服务接口文件进行编译,生成服务的API包、静态文档和元数据文件;
对所述元数据文件进行解析,获取服务接口信息中的文档信息;
根据获取到的文档信息,生成服务接口的动态文档。
一种服务接口文档生成装置,包括:
服务接口文件生成模块,用于定义包含文档信息的服务接口信息,生成服务接口文件;
服务接口文件编译模块,用于对所述服务接口文件进行编译,生成服务的API包、静态文档和元数据文件;
元数据文件解析模块,用于对所述元数据文件进行解析,获取服务接口信息中的文档信息;
服务接口动态文档生成模块,用于根据获取到的文档信息,生成服务接口的动态文档
本发明服务接口文档生成方法及装置,通过对服务接口文件编译生成服务的API包、静态文档和元数据文件,API包提供给服务开发者开发服务以及第三方调用服务,通过对元数据文件解析获取的文档信息生成动态文档。本发明根据元数据驱动转换,自动提取元数据,自动理清结构关系,准确自动生成服务接口文档(静态文档和动态文档),不需要人工逻辑参与,一键产生,快捷方便。而且,如果服务接口发生变更,服务接口文档会跟随接口变更自动更新,降低服务异常的风险。
一种服务接口在线测试工具生成方法,包括步骤:
定义服务接口信息,生成服务接口文件,其中服务接口信息包括文档信息、请求参数及其类型、返回类型;
对所述服务接口文件进行编译,生成服务的API包和元数据文件;
对所述元数据文件进行解析,获取服务接口信息;
根据获取到的服务接口信息,动态生成API的在线测试界面;
根据所述在线测试界面的响应消息显示请求数据和返回数据。
一种服务接口在线测试工具生成装置,包括:
接口文件生成模块,用于定义服务接口信息,生成服务接口文件,其中服务接口信息包括文档信息、请求参数及其类型、返回类型;
接口文件编译模块,用于对所述服务接口文件进行编译,生成服务的API包和元数据文件;
文件解析模块,用于对所述元数据文件进行解析,获取服务接口信息;
在线测试界面生成模块,用于根据获取到的服务接口信息,动态生成API的在线测试界面;
数据显示模块,用于根据所述在线测试界面的响应消息显示请求数据和返回数据。
本发明服务接口在线测试工具生成方法及装置,通过对服务接口文件编译生成服务的API包和元数据文件,API包提供给服务开发者开发服务以及第三方调用服务,根据元数据自动构造好该服务接口的测试场景,为每次API调用的输入输出数据,也即请求数据、返回数据自动加载好结构参数树,免去人工构造测试场景及测试逻辑的步骤,而且服务接口的请求参数及其类型是定义好的,能够根据服务接口的不同而自动匹配,无需手工添加参数行,提高了效率,保证了准确性。
具体实施方式
本发明针对不同的服务提供服务接口文档和在线测试工具的“一键生成”功能,其中服务接口文档生成方法及装置、服务接口在线测试工具生成方法及装置均是基于对元数据文件的解析,而元数据文件是通过对服务接口文件编译得到的。为了更好的理解本发明,下面先对元数据的含义做简单介绍。
元数据(MetaData)是关于数据的数据或者叫做用来描述数据的数据或者叫做信息的信息,是信息共享和交换的基础和前提,用于描述数据集的内容、质量、表示方式、空间参考、管理方式以及数据集的其他特征。元数据具有以下特点:
1、元数据是关于数据的结构化的数据,它不一定是数字形式的,可来自不同的资源;
2、元数据是与对象相关的数据,此数据使其潜在的用户不必先具备对这些对象的存在和特征的完整认识;
3、元数据是对信息包裹的编码的描述;
4、元数据包含用于描述信息对象的内容和位置的数据元素集,促进了网络环境中信息对象的发现和检索;
5、元数据不仅对信息对象进行描述,还能够描述资源的使用环境、管理、加工、保存和使用等方面的情况;
6、在信息对象或系统的生命周期中自然增加元数据;
7、元数据常规定义中的“数据”是表示事务性质的符号,是进行各种统计、计算、科学研究、技术设计所依据的数值,或是说数字化、公式化、代码化、图表化的信息。
在软件构造领域,元数据被定义为在程序中不是被加工的对象,而是通过其值的改变来改变程序的行为的数据。它在运行过程中起着以解释方式控制程序行为的作用。在程序的不同位置配置不同值的元数据,就可以得到与原来等价的程序行为。本发明即利用元数据性质实现服务接口文档和在线测试工具的自动生成。
为了更清晰的理解本发明,下面将结合附图对服务接口文档和在线测试工具生成的方法、装置分别进行详细介绍。
如图1所示,一种服务接口文档生成方法,包括步骤:
S110、定义包含文档信息的服务接口信息,生成服务接口文件;
S120、对所述服务接口文件进行编译,生成服务的API包、静态文档和元数据文件;
S130、对所述元数据文件进行解析,获取服务接口信息中的文档信息;
S140、根据获取到的文档信息,生成服务接口的动态文档。
服务接口信息采用基于Java(计算机编程语言)语言的IDL(InterfaceDescription Language,接口描述语言)进行定义。定义的服务接口信息包括服务基本信息、文档信息、服务策略信息、RESTful(Representational State Transfer)信息等,例如服务接口的名称及描述说明、数据类型、服务接口的错误码说明、字段实例值及默认值、字段是否为空的说明、输入参数等等。这些服务接口的元数据信息使用预设的数据结构存储。如图2所示,为本发明设计的支撑服务接口信息的数据结构实施例类图。可以采用代码加Annotation注解的形式定义服务接口信息。
如图3所示,为本发明采用IDL定义部分服务接口信息的具体实例。该示例中定义了结构体和枚举两种复杂数据类型,而结构体中又支持基本数据类型、List、Set、Map、嵌套递归结构体等复杂数据类型。代码中前面带有@的即为使用了Annotation注解来定义的服务接口信息。例如,@label和@doc标签会自动生成服务接口的名称和描述说明;@ErrorSets会自动生成服务接口的错误码的说明,字段的@sample_value会自动生成字段示例值,字段的@required或@optional会自动生成字段是否可以为空的说明;字段的@doc会自动生成字段的描述等等。
服务接口文件生成后,需要对其编译。本发明采用IDLC(Interface DescriptionLanguage Compiler,接口描述语言编译器)对服务接口文件进行编译,其中IDLC采用Scala(Scalable Language,可伸缩的语言)开发实现。对服务接口文件进行编译,即生成服务的API包、静态文档和元数据文件,其中API包提供给服务开发者开发服务以及第三方调用服务等,元数据文件驱动文档展示功能的实现。
元数据文件为服务的载体,描述了服务的一些必要信息,例如服务基本信息、文档信息、服务策略信息、RESTful信息等。如图4所示,为生成的元数据文件具体示例图,本发明的元数据文件以XML(Extensible Markup Language,可扩展标记语言)格式文件的形式存在等。
通过解析元数据文件,我们就可以获取服务接口信息,从而实现与服务相关的功能。由于元数据需通过一些特有的数据结构来存储信息,所以将服务接口信息存储到事先设计好的数据结构中,就可以利用这些信息来实现相关的功能,例如生成服务接口动态文档等。
服务接口文档可以分为静态文档和动态文档,一般通过网页的形式来展现。静态文档是针对单个服务的文档,也就是说每一个服务都有与之对应的静态文档,静态文档可以打包、拷贝。静态文档的生成发生在编译阶段,采用Scala语言对所述服务接口文件进行编译,步骤S120中生成静态文档的步骤可以包括:
编译时获取服务接口信息包含的文档信息,将获取的文档信息配以预设的UI(User Interface,用户界面)模板,生成HTML(Hyper Text Mark-up Language,超文本标记语言文件)代码,将生成的HTML代码写入对应的HTML文件中,生成静态文档。
动态文档是针对所有服务的文档,根据不同的服务展示其对应的文档内容,以动态网页的形式存在。采用TypeScript语言对所述元数据文件进行解析,步骤S140中生成动态文档的步骤可以包括:
将解析后获取到的文档信息配以预设的UI模板,动态操作DOM(Document ObjectModel,文件对象模型)树,生成动态文档。
如图5所示,为本发明根据输入的服务接口文件自动生成的服务接口文档具体实施例的示意图。可以看出,采用本发明方法实现的服务接口文档具有统一的样式,避免了由于文档编写者编译格式差异和语焉不详,造成的第三方调用者理解上的歧义。本发明服务接口文档自动生成,大大降低了服务接口文档编写的工作量,并保证了服务接口文档的准确性,并且服务接口文档会跟随接口代码的变更而自动更新,避免由于人工没有及时更新而造成的服务异常,同时服务接口文档具有丰富的展现能力,支持无限级的交叉引用等。
基于同一发明构思,本发明还提供一种服务接口文档生成装置,下面结合附图对本发明装置的具体实施方式做详细描述。
如图6所示,一种服务接口文档生成装置,包括:
服务接口文件生成模块610,用于定义包含文档信息的服务接口信息,生成服务接口文件;
服务接口文件编译模块620,用于对所述服务接口文件进行编译,生成服务的API包、静态文档和元数据文件;
元数据文件解析模块630,用于对所述元数据文件进行解析,获取服务接口信息中的文档信息;
服务接口动态文档生成模块640,用于根据获取到的文档信息,生成服务接口的动态文档。
服务接口信息采用IDL进行定义。定义的服务接口信息包括服务基本信息、文档信息、服务策略信息、RESTful信息等,例如服务接口的名称及描述说明、数据类型、服务接口的错误码说明、字段实例值及默认值、字段是否为空的说明、输入参数等等。这些服务接口的元数据信息使用预设的数据结构存储。服务接口文件生成模块610可以采用代码加Annotation注解的形式定义服务接口信息。
服务接口文件生成模块610生成服务接口文件后,服务接口文件编译模块620对服务接口文件进行编译,即生成服务的API包、静态文档和元数据文件,其中API包提供给服务开发者开发服务以及第三方调用服务等,元数据文件为XML格式文件,用于实现动态文档展示功能。
元数据文件解析模块630解析元数据文件,获取服务接口信息。服务接口动态文档生成模块640根据获取到的文档信息,生成服务接口的动态文档。
服务接口文档可以分为静态文档和动态文档,一般通过网页的形式来展现。当服务接口文档为静态文档时,服务接口文件编译模块620采用Scala语言对所述服务接口文件进行编译,如图7所示,所述服务接口文件编译模块620可以包括:
代码生成单元6201,用于编译时获取服务接口信息包含的文档信息,将获取的文档信息配以预设的UI模板,生成HTML代码;
静态文档生成单元6202,用于将生成的HTML代码写入对应的HTML文件中,生成静态文档。
动态文档是针对所有服务的文档,根据不同的服务展示其对应的文档内容,以动态网页的形式存在。当服务接口文档为动态文档时,元数据文件解析模块630采用TypeScript语言对所述元数据文件进行解析,如图8所示,服务接口动态文档生成模块640包括:
动态文档生成单元6401,用于将解析后获取到的文档信息配以预设的UI模板,动态操作DOM树,生成动态文档。
本发明服务接口文档自动生成,大大降低了服务接口文档编写的工作量,并保证了服务接口文档的准确性,并且服务接口文档会跟随接口代码的变更而自动更新,避免由于人工没有及时更新而造成的服务异常,同时服务接口文档具有丰富的展现能力,支持无限级的交叉引用等,具有统一的样式,避免了由于文档编写者编译格式差异和语焉不详,造成的第三方调用者理解上的歧义。
基于元数据文件解析的同一发明构思,本发明还提供一种服务接口在线测试工具生成方法,下面结合附图对本发明方法的具体实施方式做详细描述。
如图9所示,一种服务接口在线测试工具生成方法,包括步骤:
S910、定义服务接口信息,生成服务接口文件,其中服务接口信息包括文档信息、请求参数及其类型、返回类型;
S920、对所述服务接口文件进行编译,生成服务的API包和元数据文件;
S930、对所述元数据文件进行解析,获取服务接口信息;
S940、根据获取到的服务接口信息,动态生成API的在线测试界面;
S950、根据所述在线测试界面的响应消息显示请求数据和返回数据。
服务接口信息采用IDL进行定义。定义的服务接口信息包括服务基本信息、文档信息、服务策略信息、RESTful信息等,例如请求参数及其类型、返回类型、服务接口的名称及描述说明、数据类型、服务接口的错误码说明、字段实例值及默认值、字段是否为空的说明等等。这些服务接口的元数据信息使用预设的数据结构存储。为服务接口事先定义好相应的输入参数及其类型,则在进行在线测试时能够根据服务接口的不同而自动匹配,不需要手工添加参数行,提高了工作效率,保证了测试的准确性。可以采用代码加Annotation注解的形式定义服务接口信息。
生成服务接口文件后,采用IDLC对其进行编译,即生成服务的API包和元数据文件,其中API包提供给服务开发者开发服务以及第三方调用服务等,元数据文件为XML格式文件,用于实现在线测试功能。
在线测试工具以Web的形式展现,由于不同服务的元数据是不同的,前端需要对应地进行调整,所以前端需要一门动态语言来解析元数据,并能够操作DOM树。本发明利用TypeScript对元数据文件进行解析,它是一门面向对象的动态语言,兼容JavaScript,还具有Lambda函数,它的存在使得解析元数据变得简单而高效。通过解析元数据文件,获取服务接口信息,利用这些信息配以预设的UI模板自动生成在线测试界面,然后根据所述在线测试界面的响应消息显示请求数据和返回数据。
如图10所示,为本发明生成的在线测试工具实施例的示意图。前端根据元数据展示返回类型、服务名-版本号、方法名以及服务相关的请求参数的数据结构等。根据前端展示的界面输入相应的请求参数等,由于请求参数的数据类型是事先定义好的,所以可以设置请求参数Tips(提示)格式提示,自动校验输入的请求参数类型的合法性。后台收集请求数据并通过REST(Representational State Transfer,表述性状态传递)请求服务接口返回数据,将请求数据和返回数据展示到前端。
本发明根据元数据自动构造好相应测试场景,为每次API的调用的输入输出参数自动加载好结构参数树,免去人工构造测试场景及测试逻辑的步骤;支持基本数据类型和复杂数据类型,支持无限层级;JSON/XML格式的数据展示,可以全部展开/收起,界面美观大方;还可以设置帮助信息Tips,鼠标移动到字段名上即可展现字段说明;支持保存和载入测试数据,高效管理测试数据,提高用户体验;在线测试工具可以根据服务接口的变更自动更新,提高了效率和准确性。
本发明方法关于元数据文件生成的其它技术特征与上述服务接口文档生成方法和装置相同,在此不予赘述。
基于同一发明构思,本发明还提供一种服务接口在线测试工具生成装置,下面结合附图对本发明装置的具体实施方式做详细描述。
如图11所示,一种服务接口在线测试工具生成装置,包括:
接口文件生成模块1110,用于定义服务接口信息,生成服务接口文件,其中服务接口信息包括文档信息、请求参数及其类型、返回类型;
接口文件编译模块1120,用于对所述服务接口文件进行编译,生成服务的API包和元数据文件;
文件解析模块1130,用于对所述元数据文件进行解析,获取服务接口信息;
在线测试界面生成模块1140,用于根据获取到的服务接口信息,动态生成API的在线测试界面;
数据显示模块1150,用于根据所述在线测试界面的响应消息显示请求数据和返回数据。
服务接口信息采用IDL进行定义。定义的服务接口信息包括服务基本信息、文档信息、服务策略信息、RESTful信息等,例如请求参数及其类型、返回类型、服务接口的名称及描述说明、数据类型、服务接口的错误码说明、字段实例值及默认值、字段是否为空的说明等等。这些服务接口的元数据信息使用预设的数据结构存储。为服务接口事先定义好相应的输入参数及其类型,则在进行在线测试时能够根据服务接口的不同而自动匹配,不需要手工添加参数行,提高了工作效率,保证了测试的准确性。接口文件生成模块1110可以采用代码加Annotation注解的形式定义服务接口信息。
接口文件生成模块1110生成服务接口文件后,接口文件编译模块1120采用IDLC对其编译,生成服务的API包和元数据文件,其中API包提供给服务开发者开发服务以及第三方调用服务等,元数据文件为XML格式文件,用于实现在线测试功能。
在线测试工具以Web的形式展现,由于不同服务的元数据是不同的,前端需要对应地进行调整,所以文件解析模块1130可以利用TypeScript对元数据文件进行解析。文件解析模块1130通过解析元数据文件,获取服务接口信息。在线测试界面生成模块1140将服务接口信息配以预设的UI模板,自动生成在线测试界面,然后数据显示模块1150根据所述在线测试界面的响应消息显示请求数据和返回数据。
本发明根据元数据自动构造好相应测试场景,为每次API的调用的输入输出参数自动加载好结构参数树,免去人工构造测试场景及测试逻辑的步骤;支持基本数据类型和复杂数据类型,支持无限层级;JSON/XML格式的数据展示,可以全部展开/收起,界面美观大方;可以设置请求参数Tips格式提示,自动校验输入的请求参数类型的合法性;可以设置帮助信息Tips,鼠标移动到字段名上即可展现字段说明;支持保存和载入测试数据,高效管理测试数据,提高用户体验;在线测试工具可以根据服务接口的变更自动更新,提高了效率和准确性。
本发明服务接口在线测试工具生成装置其它技术特征与上述服务接口在线测试工具生成方法相同,在此不予赘述。
以上所述实施例仅表达了本发明的几种实施方式,其描述较为具体和详细,但并不能因此而理解为对本发明专利范围的限制。应当指出的是,对于本领域的普通技术人员来说,在不脱离本发明构思的前提下,还可以做出若干变形和改进,这些都属于本发明的保护范围。因此,本发明专利的保护范围应以所附权利要求为准。