rest - Swagger和HATEOAS之间的区别

Question

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

Answer 1

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年进行了一次精彩演讲，他explains affordances and how a state machine might be implemented through HATEOAS。除了常见或标准化的媒体类型和关系名称外，无需带外知识即可与服务进行进一步交互。以Asbjørn演讲中的烤面包机为例，烤面包机可能具有状态off，on，heating和idle，其中打开烤面包机将导致状态从off转换为on，然后过渡到heating，直到达到特定温度为止，在该温度下，状态过渡到idle，并在idle和heating之间切换，直到烤面包机关闭。

HATOAS将为客户提供有关当前状态的信息，并包括客户可以调用以链接到下一个状态的链接，即再次关闭烤面包机。在这里需要强调的是，服务器为客户端提供了客户端可能执行的每个下一步操作。客户端实现者无需查阅任何专有API文档即可使客户端能够与REST服务进行交互。此外，由于客户端将通过链接关系名称确定调用该URI是否有意义，因此URI不必具有有意义的含义或设计为传达语义表达结构。此类关系名称可以由IANA指定，也可以由诸如Dublin Core或schema.org之类的通用方法指定，也可以由充当extension attributes的绝对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并不互斥，但另一条或多或少变得毫无用处。