7810利用OpenAPI文档生成Web前端0István Koren,Ralf Klamma RWTHAachen大学,德国Aachen,德国koren,klamma@dbis.rwth-aachen.de0摘要0每天都会引入新的互联网设备和Web服务。有可用的文档格式,以API端点和参数的形式描述它们的功能。特别是在过去几年中,OpenAPI规范已经获得了相当大的影响力。存在基于Web的解决方案,可以生成带有HTML5和JavaScript的交互式OpenAPI文档。它们允许开发人员快速了解服务和设备的功能和工作原理。然而,生成的用户界面与设计师和最终用户的实际实践相去甚远。我们提出了一种方法来弥补这个差距,通过使用基于模型驱动的方法,生成最先进的响应式Web用户界面。为此,我们使用交互流建模语言(IFML)作为中间模型规范,将API和前端结合起来。我们的实现基于Web组件和SVG等开放标准。我们的工具的屏幕录像可在https://youtu.be/KFOPmPShak4上观看。0CCS概念0• 信息系统 → RESTful web服务; • 软件及其工程 →集成和可视化开发环境; 设计语言;0关键词0OpenAPI; IFML; Web Components; 交互设计0ACM参考格式:István Koren,RalfKlamma。2018。利用OpenAPI文档生成Web前端。在WWW'18Companion:2018年Web会议伴侣,2018年4月23日至27日,法国里昂。ACM,纽约,纽约,美国,7页。https://doi.org/10.1145/3184558.318874001 引言0我们的社会目前正在经历一种前所未有的引入各种尺寸和形状的新型互联网设备。例子包括笔记本电脑、智能手机和可穿戴增强现实眼镜。几乎每个消费者设备都能够通过TCP/IP和HTTP(S)与Web资源进行通信。此外,消费者设备如智能手机、平板电脑甚至智能手表都具有显示交互式HTML5页面和JavaScript的Web浏览器。在开发中面临的挑战是0本文根据知识共享署名4.0国际(CC BY4.0)许可证发布。作者保留在其个人和公司网站上传播作品的权利,并附上适当的归属。WWW'18 Companion,2018年4月23日至27日,法国里昂,© 2018IW3C2(国际万维网会议委员会),根据知识共享CC BY 4.0许可证发布。ACM ISBN978-1-4503-5640-4/18/04。https://doi.org/10.1145/3184558.31887400支持这些设备的应用程序是多样的。在后端可扩展性、可靠性和可维护性问题上,通过将软件组件化为运行微服务的虚拟容器来解决。这些服务公开应用程序编程接口(API),开发人员可以使用这些接口来创建应用程序。为了简化API的使用,已经提出了许多API文档标准;对于基于REST的Web服务,OpenAPI规范[10](以前称为Swagger)成为明显的市场领导者。围绕该规范已经形成了一系列相关工具集,提供代码生成和简单的Web前端。虽然这些工具对开发人员很友好,但并不真正适用于设计师和最终用户等非开发人员使用。例如,生成的用户界面包含许多技术细节,如JSON模式和可能的错误代码。为此,我们的主要目标是从API到Web前端自动生成耗时的用户界面创建过程。我们希望能够生成应用程序原型,其设计可以根据用户特定需求进行定制。通过这样做,我们还可以释放开发人员资源,以解决更多用户需求。在本文中,我们介绍了一种基于OpenAPI文档格式生成和设计Web前端的工具。它能够通过API与各种Web服务进行通信。我们的目标是建立一个协作平台,由领域专家、设计师和开发人员组成的整个社区可以共同开发应用程序。为了使交互尽可能简单,拖放行为和工具提示是必要的功能要求。在非功能方面,主要目标是完全依赖于已建立的Web标准,或者至少依赖于各方支持的开放规范。为了适应大量的显示形式因素,我们采用了基于模型驱动的交互设计方法,借助交互流建模语言(IFML)的帮助。概念模型对于软件工程师和数据库设计人员来说是熟悉的;特别是IFML可以用于设计前端组件之间的设备无关交互。我们的实现基于最近的W3C规范WebComponents组,以实现应用程序之间的模块化和可重用性。本文的其余部分结构如下。第2节介绍了基于服务描述生成Web前端的相关研究。第3节解释了相关的Web技术。第4节解释了概念设计。第5节解释了实现细节。第6节讨论了我们方法的优点和缺点。第7节总结了我们的文章,并展望未来的工作。0Developers Track WWW 2018, 2018年4月23日至27日, 法国里昂1https://apis.guru/openapi-directory/"$ref": "#/components/schemas/Contact"78202 相关工作0关于跨设备用户界面,研究表明已经有多种方法用于创建适用于各种应用领域的通用用户界面描述。针对Web的最重要的努力是Cameleon参考框架[5]。它定义了从任务模型到抽象UI规范再到具体UI的多步骤过程模型。Maximilien等人介绍了Swashup,这是一种用于WebAPI和服务混搭的领域特定语言[16]。它利用了像WSDL这样的服务描述,但专注于服务组合。同样,He和Yen[8]以及ServFaceBuilder[17]依赖于WSDL文件。ServFace方法生成用户界面,但是由服务开发人员编写注释驱动。Vaziri等人使用Swagger文档生成与API的自然语言交互的聊天机器人[21]。他们的系统能够通过让用户与聊天机器人交互来改进规范。作者报告说,许多RESTAPI具有复杂的JSON结构,而他们的聊天机器人是为标量输入(如字符串和日期)而设计的。Swagger也被[13]使用,该文献根据上下文属性建议用户API。对于每个服务,都会生成一个Android用户界面;目标是为各种上下文相关服务提供统一的界面。有几种方法将物联网(IoT)设备API连接到Web。Simurgh使用RAMLAPI规范语言来发现和集成物联网(IoT)设备[12]。然后,它们的功能由最终用户组合。在多供应商物联网设备的多供应商聚合领域,有一些软件产品,例如Node-RED[6]和IFTTT[9]。然而,尽管提供了强大的功能和出色的用户体验,但这些工具既不支持同步协作的多用户能力,也不基于独立于供应商的标准化符号。03 WEB技术0接下来,我们介绍我们的工具背后的标准和Web技术。首先,介绍OpenAPI规范,然后突出显示交互流建模语言(IFML)。最后,我们展示W3C Web组件标准组。03.1 OpenAPI规范0OpenAPI是一种用于RESTfulWeb服务的应用程序接口(API)文档规范[10]。它允许创建基于HTTP的机器可读的接口描述,用于文档化、生成、消费和可视化API。它以前被称为Swagger,在Web社区中得到广泛支持,并有各种围绕它构建的开源项目。标准化由Linux基金会下的Open APIInitiative领导,该组织成立于2015年底。谷歌、IBM和微软等主要公司为规范的开发做出贡献。仅APIs.guru网站目前列出了约550个公开可用的带有Swagger/OpenAPI文档的API[1]。OpenAPI文档可以使用YAML或JSON标记语言描述API;这两种格式可以相互转换而不丢失信息。下面的列表提供了一个使用YAML格式的示例OpenAPI文档。它记录了一个简单的通讯录Web服务0,其中/contacts作为单个资源,具有用于检索和删除联系人的方法。可以通过提供路径参数来检索特定的联系人。表1给出了OpenAPI文档属性背后的主要概念的非全面概述。0--- openapi: 3.0.0 servers: - description: 开发服务器 url:http://127.0.0.1:3000 info: version: 1.0.0 title: 通讯录服务description: 通讯录服务的API tags: - name: 联系人description: 关于联系人的一切 paths:0"/contacts" : get: 标签:- contact描述:返回所有联系人。operationId:getContacts 响应:0'200' :描述:所有联系人。内容:application/json:模式:类型:数组项:0"$ref" : "#/components/schemas/Contact""/contacts/{contactId}" : get: 标签:- contact描述:返回特定联系人。operationId:getContactById 参数:-in:路径 名称:contactId 描述:联系人的ID。必需:true模式:类型:整数 格式:int64 响应:0'200' :描述:特定类别。内容:application/json:模式:0delete:标签:0开发者跟踪WWW 2018年4月23日至27日,法国里昂7830表1:OpenAPI属性0属性描述0openapiOpenAPI版本信息标题和文档版本服务器具体端点URL列表安全认证和授权选项路径API路径列表,以服务器URL为前缀标签将路径分组为类别组件可重用的详细信息,如参数模式0- contact描述:删除联系人。operationId:deleteContactById 参数:- in:路径名称:contactId描述:联系人的ID。必需:true模式:类型:整数 格式:int64 响应:0'200' : 描述:联系人已删除。0'404' :描述:未找到联系人。组件:schemas:Contact:类型:对象属性:id:类型:整数 格式:int64 名称:类型:字符串lastname:类型:字符串 email:类型:字符串 Swagger UI [ 20]是一种开源软件,可以从OpenAPI文件自动生成基于HTML5的可视化和交互前端。路径以标签分组的方式呈现。交互能力非常有限,开发人员可以在文本框中输入参数来测试客户端请求和服务器响应。图1显示了由SwaggerUI生成的上述地址簿示例的HTML文档的剪辑屏幕截图。03.2 交互流建模语言0图1:Swagger UI中的地址簿示例0(OMG)是同样负责软件工程中普遍使用的UML标准的标准化机构。IFML模型是对图形用户界面的平台无关表示,可以在移动设备、笔记本电脑或可穿戴设备等设备上生成具体的用户界面。标准文档包含0开发者论坛 WWW 2018,2018年4月23日至27日,法国里昂7840通讯录0<<列表>>联系人0<<详情>>0联系人0删除动作0视图容器 视图组件0导航流事件0动作0图2:通讯录IFML模型0多个示例映射到用户界面描述语言,例如Windows PresentationFoundation、Java Swing和HTML。例如,ViewContainer可以被转换为HTML的
元素,嵌套的ViewComponents可以被转换为相应的子元素。官方的IFML网站列出了几个商业和开源的模型编辑器实现。最值得注意的是我们提到IFMLEdit.org,一个基于Web的建模工具,能够从IFML模型生成Web客户端[3]。03.3 Web组件0Web组件是一种自定义的可重用DOM元素,可以像原生HTML元素一样在DOM中使用。Web组件规范组正在标准化,成为HTML和DOM规范的一部分。自定义元素功能在DOM中添加了新的方法,用于注册新元素及其标识符,该标识符需要包含一个破折号,以区分现有的原生标签,如
和
。ShadowDOM封装了CSS样式和JavaScript代码的范围,限制在一个节点的内部子节点中。虽然这些功能正在所有主要的Web浏览器中实现,但JavaScript填充程序确保这些API的向后兼容性。Web组件是前端Web中组件化软件工程增加采用的最新表现形式。在JavaScript框架级别上类似的方法有Ember、React和Vue.js。在我们的实现中,我们使用Google维护的Polymer库的2.0版本。它使用ECMAScript6语言版本的类和混入功能。基于Polymer的高级自定义元素简化了ServiceWorker的注册和缓存,使得Web应用程序可以在没有活动Internet连接的情况下工作。Polymer还提供了遵循MaterialDesign指南[7]的高保真预设计模板元素。它们在设备类型和显示形态因素上实现了高可访问性和熟悉的用户体验。04 转换方法0在介绍所使用的标准和技术之后,我们在本节中描述了用户界面生成方法。图3给出了从OpenAPI规范到基于HTML5和JavaScript的具体用户界面的生成序列的概述。图中用相同的背景颜色突出显示相互转换的概念(从左到右)。在OpenAPI规范中,服务器端点的URL通过服务器属性和路径数组中的一个项的组合进行编码(紫色/深色突出显示)。这些信息封装在IFML模型的Action中。HTML5和JavaScript实例在提交表单时调用的方法中包含URL信息。表单本身在IFML模型中由一个视图组件表示(黄色/浅色背景)。它起源于端点的参数属性。接下来,我们详细介绍上述过程,并介绍API规范、建模和HTML5 & JavaScript实现概念之间的进一步映射。04.1 API文档到模型0用户界面生成序列的第一步是从OpenAPI文档创建IFML模型。生成的IFML模型有助于抽象平台特定的实现细节。图3中已经介绍了两种类型的转换。OpenAPI文档的服务器URL和路径属性是涉及客户端和服务器之间数据交换的每个转换的一个组成部分。两者的组合定义了服务器端点,例如,从客户端检索内容或上传输入。虽然这些信息对于后续的用户界面代码转换很重要,但在模型中没有可视化。因此,我们向模型添加语义注释。另一种转换类型是从文档的参数数组生成视图组件。OpenAPI遵循JSON模式描述语言。它描述了一个JSON数据结构并允许自动验证。用于构建结构层次的两种主要数据类型是对象和数组。对象是一个键值对的集合,而数组是一个项目列表。对象的键是字符串类型,而值和数组项可以是 object 、 array 、string 、 number 、 boolean 或 null中的任何一种。在这里,数据类型层次结构的第一级是感兴趣的。如果它是一个数组,则生成的模型元素是 List ;对象生成为 Form 和 Detail视图组件。其他类型,例如返回单个字符串的REST端点,被转换为普通的视图组件。04.2 模型到前端0在第二步中,生成的IFML模型根据HTML5和JavaScript转换为具体的用户界面。用HTML元素表示IFML概念的基本原理在官方IFML规范附录E[19]中有描述。在那里,整个模型被映射到一个WebSite元素,它代表HTML页面的主
标签。其他映射包括将ViewContainers映射为
标签,将Form ViewComponents映射为等效的