第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂1869一种自然语言驱动的Web API自动开发方法Gherkin2OAS阿纳斯塔西奥斯·迪马尼迪斯塞萨洛尼基亚里士多德大学anasdima@issel.ee.auth.gr基里亚科斯角Chatzidimitriou亚里士多德塞萨洛尼基大学塞萨洛尼基kyrcha@issel.ee.auth.gr安德烈亚斯湖塞萨洛尼基亚里士多德大学塞萨洛尼基asymeon@eng.auth.gr摘要加快Web服务的开发过程，同时坚持高质量的软件标准是软件行业的典型要求。这就是为什么行业专家通常建议采用“由发展驱动”的方法来解决这一问题。在本文中，我们提出了这样一种方法，采用规范驱动的开发和行为驱动的开发，以促进Web服务的需求获取和规范的阶段。此外，我们还介绍了gherkin2OAS，一个软件工具，渴望弥合上述开发方法。通过建议的方法和工具，可以快速设计和构建RESTful服务，同时确保正确的功能。CCS概念• 软件及其工程→需求分析;API语言;软件开发技术;关键词开放API规范RESTful API;行为驱动开发ACM参考格式：Anastasios Dimanidis，Kyriakos C. Chatzidimitriou和Andreas L.赛米-奥尼 迪 斯 。 2018. 自 然 语 言 驱 动 的 Web API 自 动 开 发 方 法 ：Gherkin2OAS。 在WWW '18伴侣：2018年网络会议伴侣，2018年4月23日至27日 ， 法 国 里 昂 。 ACM ， New York ， NY ， USA ， 6 页 。https://doi.org/10.1145/3184558.31916541介绍在典型的软件开发生命周期中有效地满足客户需求一直是业界和学术界关注的主要问题。新的，“由”软件工程方法驱动的，如行为驱动开发和敏捷宣言已经引入，规定了软件工程师和客户之间的持续沟通。这些方法渴望在过程的任何阶段接受变化，同时允许软件需求的演变本文在知识共享署名4.0国际（CC BY 4.0）许可下发布作者保留在其个人和公司网站上以适当的归属方式传播作品的权利。WWW©2018 IW3C2（国际万维网会议委员会），在知识共享CC BY 4.0许可下发布。ACM ISBN 978-1-4503-5640-4/18/04。https://doi.org/10.1145/3184558.3191654另一方面，Web应用程序和Web服务的开发自从采用“Web作为应用程序平台”以来面向REST的架构及其配套工具虽然高效，但主要关注软件的设计和开发方面，并将需求到设计元素的过渡阶段然而，这种转换需要专业知识，并且在许多情况下，可能导致软件发布延迟和人力浪费。认识到这种适应当前开发环境的必要性，我们提出了一个（半）自动化的方法，结合行为驱动开发（BDD）原语-链接到基 于 Kent Beck 另 一 方 面 ， SDD 规 定 了 OpenAPI 规 范（OAS），RAML和API蓝图等Web API规范的使用，以确保验证，一致性和可重用性。我们的自然语言驱动开发（NLDD）方法试图将上述两种开发策略合并。根据NLDD的说法，当需要开发Web服务时，人们会讨论它应该提供什么这些讨论最终导致了基于Gherkin语言的服务的自然语言描述文档，主要用于BDD。这一高层次的文件自动翻译成一个有效的OAS文件，通过采用gherkin2OAS，低代码工具，开发了用于此目的。在过程的最后，开发团队手中有两个文档：业务文档和技术文档，它们通过软件过程相互连接因此，业务文档上的任何更改都可以立即描述到技术文档中，同时收获了BDD的好处-在测试框架中使用，用自然语言编写的半结构化文档-以及SDD- 通 过 客 户 端 和 服 务 器 脚 手 架 自 动 生 成 代 码Gherkin2OAS采用自然语言处理（NLP）技术来处理Gherkin文档的内容，并生成手头服务的有效OAS版本2[4]文档根据NLDD，开发RESTful Web Service的过程包括反馈循环中的三个阶段：第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂1870(1) 讨论，决定和文件服务功能在小黄瓜语言。参与讨论的至少一个人必须了解所提议的方法。(2) 使用开发的gherkin2OAS生成OAS模型软件工具，并在其背后实现REST API。(3) 反馈步骤：验证预期行为NLDD的主要目标是加强所有相关方之间的沟通更具体地说：业务涉众和产品所有者是最了解领域的人，因此他们参与开发过程越多，解决方案就越好通过拥抱BDD和引入支持自然语言的文档，我们声称朝着跨方参与和客户满意度迈出了重要的一步开发人员之间的沟通也可以证明是非常困难的，只使用技术文档。开发人员可能在不同的API端点上工作，并且不熟悉软件功能在Gherkin文件中使用Feature关键字进行描述每个功能都包含几个场景，以满足涉众的需求。每个场景都是系统在特定情况下应该如何运行的一个具体示例。如果一个人实现了所有定义的场景所记录的行为，那么它应该会产生预期的特性行为。Scenarios使用Scenarios关键字声明。所有场景都遵循相同的模式：它们从系统状态的上下文开始此模式在Gherkin文件中用Given表示。. . 当.. .那么关键字序列：清单1：Gherkin：Given..当...然后S C E N A R I O：S U C E S F L提款从帐户中的存款给定我有 一百块I n 我 账户 # 他不C o n t e x t当我要求20美元时#t e v e n t（s）那么20 美元应该是他的了 结果完整的API，这可能是一个巨大的OAS文档。另外，newcom-用户可能会发现很难理解和采用像OAS这样的技术文件。在这两种情况下，自然语言描述将允许更快地理解业务领域，并更平滑地过渡到团队此外，用自然语言记录服务比用技术语言更直观，即使对于开发人员也是如此。整个Web服务总是以非技术和技术两种方式记录两个束总是通过软件过程彼此连接。它通过这个过程，验证了讨论的技术可行性。从技术方面来看，正在使用一个被广泛接受的规范标准，即OpenAPI规范。因此，第三方开发人员将通过技术规范或自然语言描述更容易地使用Web服务。本文组织如下：在第2节中，我们通过的概念，基于小黄瓜的Web服务文档，而在第3节中，我们描述了小黄瓜和OAS概念之间的映射第4节介绍了gherkin2OAS工具，第5节讨论了相关工作。最后，在第6节中，我们讨论了模糊的主题，开放的问题和未来的工作。2基于黄瓜的文档为了用自然语言记录Web服务，我们使用了Gherkin语言：[2]的文件。Gherkin的目标是让利益相关方自己设想使用该系统。通过这个过程，涉众和开发人员创建在Gherkin中，验收测试记录在Gherkin文件[2，18]中，该文件使用特殊的关键字来开发其结构和含义：（i）特征（ii）背景（iii）情景（iv）给定(v)当（vi）然后（vii）和（viii）但是（ix）*（x）情景大纲(xi)例子.方案中的每一行都称为一个步骤。可以使用关键字And和But将更多步骤添加到场景的每个Given、When和Then部分：清单2：Gherkin：And ButS C E N A R I O：Attempt withdrawal us i ng s to l e ncardGiven I have $100 in my account但是我的卡片 I s 在v a l id当 我 r e q u e s t $50然后 我 卡尔应该 不 被 r e tur n e d和我应该被to l d到c o n t a c t银行Gherkin还支持数据表，因为场景中的步骤可能描述的数据Gherkin允许在步骤下面放置这样的细节：清单3：小黄瓜：数据表给定这些用户：| 数据库|d a t e o f b i r t h||迈克尔J A C K S O N|八月二十九小行星1958|| E L VIS|日8、一九三五年|2.1NLP-小黄瓜限制我们认为，使用小黄瓜连同NLP单独，产生一个模糊的一组可能的自然语言描述。此外，由这样的过程定义的整个系统将严重依赖于所采用的NLP机制的性能，并且因此将是不可靠的。相反，这个概念是用户应该遵循一组关于如何用自然语言记录Web服务的说明1。说明很直观，很容易遵循。当用户执行gherkin2OAS软件工具时，自然语言被翻译成规范。通过这种方法，系统的可靠性通过遵守所提供的说明来验证只要用户遵循文档规则，他/她就可以确保通过以下方式生成有效的OpenAPI规范：1 https://github.com/anasdima/gherkin2oas/blob/master/Gherkin-Instructions.pdf···第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂1871小黄瓜2OAS。最终OpenAPI规范的验证在gherkin2OAS工具中使用swagger验证器2执行。如果用户不遵循指令，那么输出肯定是无效的。考虑到上述几点，小黄瓜的概念和OAS元素之间的映射进行了设计。3GHERKIN到OPENAPI映射由于Gherkin语言中的场景描述了状态转换，而OpenAPI规范用于记录RESTful API，因此这两个概念之间存在自然的联系因此，在某种意义上，用Gherkin描述Web服务的行为与在抽象级别上描述具象状态转移是一样的。此外，业务涉众最了解的域应用协议3与REST之间存在关系。它们都描述了状态转换。从小黄瓜，我们采用了关键字：功能，背景，场景，给定，当，然后，和，但和数据表。至于美洲国家组织，也通过了一个要素子集4。3.1资源在第一级，Web服务的描述被组织在服务将公开的资源中。这实际上意味着每个资源都在其自己的“资源文档”中用Gherkin语言描述这种基于资源的方法具有以下优点：资源的概念足够抽象，适合任何系统描述（敏捷友好）。Web开发人员对使用资源很熟悉。以如此清晰的方式组织Web服务的描述，降低了gherkin2OAS软件工具的复杂性。作为一项技术优势，资源分离意味着设计上的多线程支持，因为每个资源文档都可以独立处理。资 源 文 档 是 用 Gherkin 语 言 编 写 的 文 件 ， 扩 展 名为.resource文件的名称是资源的名称，也是REST API路径的一部分例如以绘制其他特征。这就是When。. .然后以映射为核心提出了基于Gherkin的方法。清单4：基于Gherkin的文档：When..然后当 我 提交 一错支付为一个或者我应该看到一条留言“错了金额”3.3动词、参数和模型When步骤的动词被映射到四个主流CRUD HTTP动词之一：GET，POST，PUT，DELETE [3]。另另一方面，When步骤的名词被映射到请求参数。清单5：基于Gherkin的文档：名词参数当我通过它的ID检索到数据库时高级参数化可以通过Gherkin的数据表实现。每一行（或列，因为两个表的方向都支持）可以保存某种类型的数据。第一列是必需的，包含参数的名称，第二列是参数示例，第三列是参数值范围。该规则允许我们将Gherkin数据表映射到包含参数类型和范围（从示例中导出）的丰富OAS参数模式。清单6：基于Gherkin的文档：数据表当您按产品的日期和名称购买产品时| 12 / 0 4 / 2 0 1 7 |1 2/0 4/2 0 1 7 || 名称 |'比克埃'|当我看到一个数据集并且看到一个数据范围时| 1 2 / 0 4 / 2 0 1 7 0 3：0 5 |1 2/0 4/2 0 1 7 0 3:0 5 ||端 d at e|1 2/0 4/2 0 1 7 1 2：0 5|当我告诉你 数据段的设置为|c l i e n t_n a m e s|c l i e n t_s u r e n ames||['约翰'，'尼克']|['安德鲁'，'罗斯']|| 最大 of 10| 最大 of 10|product.resource文件可能导致/api/product端点。.resource扩展名是必要的，这样gherkin2OAS工具就可以将资源文件与其他任何文件区分开来。3.2给定当...然后为了实现Gherkin场景到OAS的所需映射，我们利用了Gherkin的状态机逻辑。因此，When步骤表示OAS世界中的请求，而Then步骤表示响应。然而，由于最终目标是帮助开发人员专门生成RESTfulWeb服务，此外，如果步骤语句以分号（：）结束并包含名词，则可以命名数据表，以便它们可以表示OAS模型应该澄清的是，数据表可以在When和Then步骤中使用。清单7：基于Gherkin的文档：模型当 我更新的产品：|name|'包'|| D e s c r i p t i o n |10年 s l o t s '||'s点'|' s p o r t s '|我们需要考虑REST的无状态性。作为结果，在RESTfulWeb服务描述中，Given步骤不像其他两个步骤那样平滑，因此被使用2https://pypi.python.org/pypi/swagger-spec-validator3https://en.wikipedia.org/wiki/Domain_Application_Protocol4https://github.com/anasdima/gherkin2oas/blob/master/OpenAPI-Specification-v2-support.PNG支持必需和非必需参数默认情况下，所有提到的参数都按需处理但是，如果在同一资源文件中用不同的参数描述了两次相同的操作（或模型），则仅将不同描述之间的公共参数按需处理。····第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂18723.4响应响应仅在Then步骤中描述，它可以包含三种不同类型的句子：(1) 描述模型的句子（参见上一节）。(2) 描述响应消息的句子。(3) 描述指向另一资源的链接的句子响应消息由引号中的短语提取引号中的实际短语被进一步分析，以基于常见的HTTP约定提取状态代码。清单8：基于Gherkin的文档：响应消息和状态代码当 我提交 一 错 支付 为 一个 奥尔德尔| 200| 2 0 0|然后 我应该s e e一 消息这是个错误的数目此外，考虑到Web服务可以是完全RESTful的，并且包含超媒体作为应用状态引擎（HATEOAS）的概念[8，12，13，16]，所提出的方法支持HATEOAS。如果Then步骤中的句子包括动词和另一个（已经记录的）资源的名称，则该句子被映射到生成的OAS中的状态转移。清单9：基于Gherkin的文档：响应消息和到其他资源的S C N A R I O：提交 新闻# 给定 t h a t 我 有 一 B a s k e t 与 p r o d u c t s当 我提交 一个 奥尔德尔| order_document | 电影|然后一个新的 命令是“S u c c e s f ul l y”，并且 我 应该被 促使 到 提交 一支付和 我 有 的 我的天 到审查的我有 的 我的天 到 c a n c e l 的 o rd er r并且我有更新o rd er r的由于OAS版本2不直接支持HATEOAS5，因此我们使用了x-*运算符。因此，在转换为OAS之后，HATEOAS链接数组将包含在响应对象内的x-links对象这是我们唯一使用的OAS扩展。3.5角色、资源层次结构和注释OAS中的角色和路径层次结构使用“给定”步骤来支持。由于REST是无状态的，因此Given步骤可以用于设置不同类型的上下文：哪个参与者正在执行场景或者两个资源之间的关系是什么。这种上下文可以在资源文件的“背景”部分或场景的“给定”步骤中描述在“背景”部分中，如果提到两个资源名称背景：给定 的I d外来资产 一个 未缴奥尔德尔此外，如果给定句子包含一个角色（以名词的形式），则给定句子之后的内容仅与该角色相关（许可方面）。如果角色是在Background部分声明的，那么文档中描述的所有Gherkin场景但是，如果角色仅在场景的Given步骤中声明，则只有该场景与角色相关目前，场景中的Given步骤只能用于描述角色。清单11：基于Gherkin的文档：角色S C N A R I O：去除 产品 从s i t e鉴于我作为一名数据管理员被解雇，当我删除一个产品时 i t 's name那么我应该查看详细的产品|name|'包'|| 斯兹埃|五个|| c o lo r|'b l u e'|| 电子邮件 | [ 1个 二、三 四]|最后，文件中支持使用“#”注释注释可以用来为我们刚刚描述的规则增加更多的灵活性，因为它们总是会它们仍然是自然语言描述，可以显着提高文档的可读性。 所有以前的规则都组织在一个文件中，该文件与gherkin2OAS软件工具一起提供。清单12：基于Gherkin的文档：一个资源文件F e a tur e：支付费用#POST/o r d e r/{o r d e r_i d}/付款背景：给定 一个未缴o rd e r的idS C E N A R I O：支付费用当 我提交 一 支付 为 一个 奥尔德尔| 量 |28.二个|| d at e|8/2/2 0 1 7 1 2：3 2|然后我应该被 促使到视图的奥尔德尔S C N A R I O：当我提交时，支付更多的钱一错支付 为 一个 或者我应该看到一条留言“错了金额”和我应该被促使到提交一付款，并应提示我查看订单并且其中一个是当前描述的，则后者是前者的孩子从某种意义上说，这是指所描述资源的路径名将显示层次关系，即/api/parent/child。清单10：基于Gherkin的文档：资源层次结构5https://github.com/OAI/OpenAPI-Specification/issues/5774GERKIN2OASgherkin2OAS软件是用Python 3编写的，它是根据前面描述的基于Gherkin的规则开发的，用于将Gherkin文档化的资源文件转换为OAS文档。它由两个主要单位组成：NLP引擎和格式化器。第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂1873NLP引擎解析资源文件，执行预处理步骤，然后从基于小黄瓜的自然语言生成技术模型。该模块的设计目标是尽可能少地使用机器学习，以避免不可预测的结果。 NLP引擎通过资源执行自顶向下的分析。它从角色和关系开始，然后是请求和响应，最后是参数、模型、状态代码和HATEOAS链接。它使用常见的NLP技术[9]，如标记化，POS标签和单词列表，从自然语言中提取技术信息NLP 引擎支持OpenAPI规范的大多数数据类型，这些数据类型是从数据表中的参数示例派生的另一方面，格式化器接收由NLP引擎生成的技术模型作为输入其职责是将技术模型该 技 术 模 型 包 含 两 个 子 模 型 ： 1 ） 资 源 文 件 之 间 的HATEOAS转换和2）Gherkin场景之间的转换这两个子模型由绘图器使用，该绘图器基于检测到的资源关系绘制REST API的两个图。第一个图（图1）称为Resource Graph，显示资源之间的转换。第二个图（图2）称为应用程序状态图，显示应用程序状态之间的转换，在Gherkin世界中，是从场景到场景的转换第二个图是第一个图的更详细版本它有两个版本，一个技术版本和一个非技术版本，其中转换动词和响应消息分别来自OAS和基于Gherkin的文档。资源图和应用程序状态图可用于验证服务的预期功能。它们还可以用于进一步分析API的技术方面，例如性能、到达资源所需的转换等。图1：Gherkin2OAS：资源图5相关工作在[7，14，15]中，研究目标是开发软件工具，以降低软件开发的成本和速度作为这项研究的一部分，NLP方法已经开发出来，从软件需求文档中提取功能，由人类使用需求本体图注释。之后，软件工具接收注释文本作为输入，并产生技术模型作为输出。在这项工作之后，我们建立在现有的广泛技术，如Gherkin和OAS，而不是定制的，以便我们的方法对开发团队产生更大的影响。此外，在[10]中，使用NLP从Gherkin场景此外，在[6]中，作者建议对现有的Gherkin场景进行建模，以便它们可以被基于模型的测试工具所使用，并且可以实现场景间的交互。最后，[11]还提出了Gherkin语言的建模概念，最终被翻译成代码。在我们的案例中，我们使用轻量级NLP技术将Gherkin构造转换为OAS规范，这些规范可以进一步用于构建客户端和服务器代码。6讨论在本文中，我们展示了如何将两种已建立的软件开发方法组合成一种方法，以改进整个开发过程。我们通过将HATEOAS和OAS概念集成到建议的解决方案中，调整了这个概念，使其能够最好地与RESTful开发一起目标是为开发团队提供敏捷的RESTful API开发策略。即使我们的重点是提供一个强大的方法和工具，以规范转换的要求，以弥合沟通障碍，这项工作的结果也可以帮助定量的方式脚手架的Web服务的源代码从OAS规范使用的工具提供的开源社区。 已经证明，将自然语言表达的需求转换为源代码可以提高开发人员的生产力[19]。我们的方法中的主要挑战之一是保持自然语言的优点，同时保持确定性的结果。有人可能会说，实现的NLP规则限制了用户以更自然的方式表达需求然而，根据资源文件对系统的描述解决了这个问题。这是因为，即使单个文件中的描述必须简短而具体，但在多个资源文件和场景中描述服务最终会让用户感到非常冗长通过所提出的设计，我们试图引导用户在段落大小上表现力，但在资源和场景计数上。此外，注释可以在资源文件中用作注释，以便在不影响转换结果的情况下为文档增加更多的表达能力。另一个讨论点是关于所提出的方法是否值得学习的辩论，而不是在OAS中直接编写。然而，所提出的解决方案不用于替代OAS。主要目标是加强Web服务开发中涉及的各方之间的通信。当然，至少需要OAS的基本知识，否则该工具将第九届Web API和服务架构WWW 2018，2018年4月23日至27日，法国里昂1874图2：Gherkin2OAS：状态图对开发者没有任何用处此外，应该注意的是，直接在OAS中编写服务可能是一个非常繁琐的过程，特别是对于大型服务。另一方面，我们的实验表明，在我们的两个测试场景6中，211和269行小黄瓜分别映射到909和898行OAS。在未来的工作方面，可以采用OpenAPI规范版本3。我们使用OAS版本2，因为它是我们开发此方法时唯一可用的版本在版本3中，嵌套参数（更改3）和HATEOAS（更改7）得到了更好的支持。此外，OAS中的多态性（multipleof、oneOf、anyOf、allOf）可以用自然语言支持，但由于技术性更强，它可能最后但并非最不重要的是，整个系统可以集成到一个IDE中，该IDE将知道我们的方法和将生成OAS和动态图表最后可以找到gherkin2OAS工具7，使用视频[4] [n.d.]。OpenAPI规范.https://github.com/OAI/OpenAPI规范。（[n. d.]）。[5] 肯特·贝克2002年测试驱动开发：通过示例。艾迪生·韦斯利·朗曼[6] Christian Colombo，Mark Micallef，and Mark Scerri.2014年验证Web应用程序：从业务级规范到基于模型的自动化测试。141（03 2014）。[7] Themistoklis Diamantopoulos ， Michael Roth ， Andreas Symeonidis ， andEwan Klein. 2017年。软件需求作为自然语言处理的应用领域语言资源和评估（02 2017），1https://doi.org/s10579-017-9381-z[8] 罗伊·托马斯·菲尔丁两千架构风格和基于网络的软件架构设计（2000年）的第10/2000号决议。[9] 从软件行为的自然语言描述自动生成测试。2009年信息检索导论。北京：清华大学出版社.[10] 苏尼尔·卡马拉卡尔2013.从软件行为的自然语言（2013年）。[11] Thomas Mayer Falk Pappert和Oliver Rose 2015. 基于自然语言的仿真建模方法。在生产和物流模拟。[12] Leonard Richardson和Mike Amundsen2013年。 RESTful Web APIs（1 ed.）.演示8、资源文件9的完整示例以及它们在作为脚注提供的URL中生成的OpeAPI规范10ReillyMedia.[13] Leonard Richardson和Sam Ruby2007年RESTful Web服务媒体（第1版）。奥赖利引用[1] [n. d.]。行为驱动发展。https://en.wikipedia.org/wiki/驱动开发。（[n. d.]）。[2] [n. d.]。维基百科. https://github.com/cucumber/cucumber/wiki/Gherkin的网站。（[n. d.]）。[3] [n. d.]。HTTP动词。https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html的网站。（[n. d.]）。[在线; 2018年6月16日访问]。6https://github.com/anasdima/gherkin2oas/tree/master/examples7https://github.com/anasdima/gherkin2oas8https://www.youtube.com/watch? v=G5TNixy-dEc9https://github.com/anasdima/gherkin2oas/tree/master/examples10 https://github.com/anasdima/gherkin2oas/tree/master/generated-specifications[14] Michael Roth，Themistoklis Diamantopoulos，Ewan Klein，and Andreas Symeoni-dis. 2014年软件需求：语义解析器的新领域（2014年）。[15] 迈克尔·罗斯和伊万·克莱因。2015.用基于本体的语义角色标注器解析软件需求。在IWCS研讨会上：语言和本体论2015。[16] Jim Webber ， Savas Parastatidis ， and Ian Robinson.2010 年 。 REST inPractice（1）.Reilly Media.[17] 肯特·贝克和辛西娅·安德烈斯。一九九九年。极限编程解释艾迪生-韦斯利。[18] Matt Wynne和Aslak Hellesoy 2012. 黄瓜书实用的书架。[19] Christoforos Zolotas ， Themistoklis G. 基 里 亚 科 斯 ？ 迪 亚 曼 托 普 洛 斯Chatzidim- itriou和Andreas L.西蒙尼迪斯2017.从需求到源代码：RESTfulWeb服务的模型驱动工程方法。自动软件。Eng.24，4（2017），791-838。https://doi.org/10.1007/s10515-016-0206-x
我的内容管理
展开
