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

Question

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

使用 HATEOAS、HAL 或 JSON-LD 等与 Swagger 结合修改文档本身是否有任何优势？

Here是某人将 Swagger 与 HAL 结合使用的示例。

Answer 1

就像 sampada 所说的那样 - swagger 和 HATEOAS - 为您的 api 的不同维度增加更多值(value)。

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

HATEOAS 在客户端使用时将为您的 API 增加值(value)。HATEOAS 提供的链接使您可以链接 api 的不同部分(即:资源)，而无需在应用程序客户端代码中对这些链接进行硬编码。

假设您有一份契约(Contract)以及一些与之相关的文件。对此进行建模的一种非常常见的方法是使用两种资源:

• 契约(Contract)资源 - 为您提供列出、添加、删除、更改契约(Contract)的操作；
• 文档资源 - 为您提供列出、添加、删除、更改文档的操作

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

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

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