你应该将Swagger与HATEOAS / HAL / JSON-LD结合使用吗？

Question

我使用Swagger为我的ASP.NET Core API使用Swashbuckle，它在一个单独的文档中描述了我的API，并为所有这些信息提供了一个很好的UI。

使用像HATEOAS，HAL或JSON-LD这样的东西是否有任何优点可以与Swagger一起修改文档本身？

以下是使用Swagger和HAL的人的示例。

Answer 1

除了使用Swagger之外，将HATEOAS集成到API代码中还有一定的优势。

Swagger通过使表单看起来很好且易于呈现来为您的API添加表单，以便可以轻松编写客户端代码，同时通过将文档与代码集成，使文档成为一项不那么无聊的任务。 不用说，它还节省了在编码结束后完成文档所需的额外时间。 从这个意义上讲，它有点革命性。

另一方面， HATEOAS通过启用Level 3 RMM使您的API可自行发现。 这样可以更轻松地将一个API导航到另一个API。 我们的想法是拥有一个客户端可以使用的基本URL，并从该基本URL发现其余的REST API。

现在问题是，为什么两者兼而有之？ 好吧，它只是为您的Restful API添加了更多维度，并为客户提供了更少的编码工作选择。 谁不想要那个？

Answer 2

像sampada所说的那样 - 招摇和HATEOAS - 为你的api的不同维度增加了更多的价值。

Swagger将为开发生命周期增加价值，使您的api在开发时更易理解和可浏览。

当客户使用时， HATEOAS将为您的api增加价值。 HATEOAS提供的链接使您可以链接api的不同部分（即：资源），而无需在应用客户端代码中对这些链接进行硬编码。

假设您与一些与之相关的文件签订了合同。 一种很常见的建模方法是使用两种资源：

• 合同资源 - 为您提供列出，添加，删除，更改合同的操作;
• 文档资源 - 为您提供列出，添加，删除，更改文档的操作

要将这两者链接在一起，您可以在包含相关资源数组的两个资源模型中添加字段。 此外，您还必须在客户端应用程序中实现这些隐式知识。 这样，您（将）随着时间的推移向您的资源表示添加混乱，并使用有关与其他对象的关系的信息进行污染。

这就是HATEOAS发挥作用的地方，既可以将业务信息从业务对象中移出，也可以提供统一的方式来处理这些关系。 现在，两个资源业务对象都包括一个标准化的头或值字段，其中包含有关当前资源的所有关系的信息。 例如，一个合同资源现在有3个链接，其中rel-attribute“document”链接到相应的文档资源，1个链接的rel-attribute“order”链接到此合同产生的订单。

据我所知， JSON-LD用于规范化不同API的词汇表，使其更容易并排使用。 有些人可能会使用firstName和lastName作为Person对象属性，而其他人则会使用名为givenName和familyName的属性。 使用JSON-LD，您可以将两个对象映射到通用名称。 您可以考虑查看此链接： DZone - Json-LD

Answer 3

考虑一下Hydra：

http://www.hydra-cg.com/

Hydra是JSON-LD的词汇表，允许您将超媒体控件嵌入到数据中。 此外，您可以提供API文档端点与Swagger定义类似的角色。 我喜欢Hydra的是，超媒体控件被烘焙到响应中，而不是某种服务定义中的带外。 JSON-LD和Schema.org绝对值得研究，因为谷歌和微软都在他们的产品中支持它们。

Hydra仍然相对较新，因此可用的工具不像Swagger那样强大。