Swagger和HATEOAS之间的区别

谁能解释Swagger和HATEOAS之间的区别。我可以搜索很多次,但是没有朋友可以解释这两个方面的正确详细答案。

回答:

Swagger和HATEOAS IMO之间的主要区别(未包含在接受的答案中)是Swagger仅用于RPC’sque

API。但是,此类API实际上与REST无关。

还有一个更广泛的误解,即通过HTTP交换的任何东西都是自动RESTful的(〜符合REST建筑风格),事实并非如此。REST只是定义了一组约束,这些约束不是选择或选项,而是强制性的。从开始到结束。没有RESTful并没有什么错,但是称这样的架构REST是错误的。

Swagger描述了可以在端点上执行的操作以及需要发送到服务的有效负载(包括标头和预期的表示格式),还描述了客户端可能期望作为响应。这使得Swagger既可以用作API的文档,也可以用作测试框架。由于Swagger与API紧密耦合,因此其行为非常类似于典型的RPC服务描述,即类似于SOAP中的WSDL文件或RMI或CORBA中的存根或骨架类。如果端点发生更改或有效负载中的某些内容发生更改,则根据Swagger文档实施的客户端可能会随着时间的推移而中断,只是重新引入了典型RPC实现所具有的相同问题。

另一方面,REST和HATEOAS则是为进行灾难转移和进一步开发而设计的。REST不是协议,而是一种架构风格,它描述了分布式系统中客户端和服务器之间的交互流。它基本上采用了使Web如此成功的概念并将其转换到应用程序层。因此,适用于可浏览Web的相同概念也适用于REST。因此,HATEOAS(链接的使用和支持,链接关系和链接名称)的行为类似于Web也不是奇迹。

在设计REST体系结构时,考虑一种状态机是有益的,服务器在该状态机中提供客户端需要采取进一步措施的所有信息。AsbjørnUlsberg在2016年进行了一次精彩的演讲,他在演讲中解释了可负担性以及如何通过HATEOAS实现状态机。除了常见或标准化的媒体类型和关系名称外,无需带外知识即可与服务进行进一步交互。在烤面包机例子阿斯比约恩给他谈话的情况下,一个烤面包机可以有状态offonheatingidle在那里把一个烤面包机上会导致状态转变,从offon后面一个转变heating,直到一定的温度达到其状态过渡到idle并在idle和之间切换,heating直到烤面包机关闭。

HATOAS将为客户提供有关当前状态的信息,并包括客户可以调用以链接到下一个状态(即再次关闭烤面包机)的链接。在这里需要强调的是,服务器为客户端提供了客户端可能执行的每个操作。客户端实现者无需查阅任何专有的API文档即可使客户端能够与REST服务进行交互。此外,由于客户端将通过链接关系名称确定调用该URI是否有意义,因此URI不必具有有意义的含义或设计为传达语义表达结构。此类关系名称由IANA通过通用方法(例如Dublin

Core或schema.org)指定。或通过绝对URI充当扩展属性,这些扩展属性可能指向人类可读的描述,并且可能还会通过鼠标悬停的工具提示等将其传播给用户。

我希望您能自己看到,仅需要Swagger即可描述RPC Web-API,而无需遵循REST体系结构设计的应用程序。通过REST

API交换的消息应包括客户端在下一次状态转换时做出明智选择所需的所有信息。这样,将这样的消息流和交互设计为状态机是有益的。


更新:

Swagger和HATEOAS如何互斥?前者记录了您的端点(使自动生成代码成为可能),而后者则向您的端点添加了元信息,这些信息告诉消费者它们可以做什么(即哪些其他端点可用)。这些是完全不同的东西。

我从来没有说过它们是互斥的,只是它们有两个不同的目的,如果您遵循一种方法,则另一种方法或多或少会变得毫无用处。但是,同时使用这两者没有任何意义。

让我们将讨论移至Web领域,因为这可能更容易理解,并且REST实际上只是对Web上使用的概念的概括,因此执行此步骤是自然的,并且在设计REST体系结构方面也是一个很好的建议。一般。考虑一下您作为用户想要向服务器发送一些数据的情况。您以前从未使用过该服务,因此您基本上不知道请求的外观。

在Swagger中,您将调用终结点文档,选择最有可能解决您任务的选项,了解请求的外观,并将测试用例侵入您的应用程序,最终生成HTTP请求,该请求发送到各自的位置。自动生成代码可能会节省您一些时间,尽管您仍然需要将存根类集成到应用程序中并至少对整个事物进行一次测试以确保安全。如果以后需要集成该API或其他API的第二个服务,则需要从头开始并查找Swagger文档,生成或修改交互代码并将其集成到您的域中。涉及大量手动步骤,并且在更改API的情况下,您需要更新客户端,否则客户端可能会停止工作。

但是,在Web示例中,您仅启动浏览器/

Web客户端,调用相应的URI,该URI允许您将数据发送到服务器,服务器很可能会向您发送HTML表单,您只需要填写并单击发送即可。按钮将请求自动发送到服务器,服务器将开始处理该请求。这是HATEOAS。您使用给定的控件来驱动工作流程。服务器会教您的客户提出有效请求所需的每一个细节。它为您的客户端提供了目标URI,以将请求发送至该客户端,应使用的HTTP方法,并且通常还隐含有效负载应位于的媒体类型。此外,它还为您的客户端提供了预期和/或有效负载应包含的受支持元素。也就是说,该表格可能需要您填写几个输入字段,在一组给定的选项中进行选择,或使用其他一些控件(例如日期或时间选择器值)将其转换为对您有效的日期或时间表示形式。您需要做的就是在Web客户端中调用相应的资源。没有自动生成,没有与浏览器/应用程序集成。使用其他服务(来自相同或不同的提供程序的服务)很可能将以相同的方式工作,因此只要支持交换媒体类型的请求和响应,就无需更改或更新HTTP客户端(浏览器)。

在您依赖Swagger

RPC’esque文档的情况下,该文档是如何与服务进行交互的真相。混合一些HATEOAS信息不会给您带来任何好处。在Swagger案例中,随处携带附加的元信息,这些元信息毫无明显的理由而使请求/响应膨胀,因为所有必需的信息都在参考文档中给出,因此可以肯定地导致人们开始质疑该信息的合理性。该服务的开发商,并要求减少有效载荷。只需在SO上查看一会儿,您就会发现足够多的问题,询问如何进一步优化交互,以及如何在将消息处理每个小请求且完全不使用响应缓存的情况下将消息大小最小化。对于HATEOAS,指向外部引用只是没有用,因为这种体系结构中的同位体很可能已经支持实现于其中的所需必需品,例如URI,HTTP和相应的媒体类型。如果使用自定义媒体类型,则可以在运行时通过插件或附加组件动态添加支持(如果支持)。

因此,一旦您决定选择一条路线或另一条路线,Swagger和HATEOAS并不互斥,但另一条或多或少变得毫无用处。

以上是 Swagger和HATEOAS之间的区别 的全部内容, 来源链接: utcz.com/qa/432188.html

回到顶部