您应该将 Swagger 与 HATEOAS/HAL/JSON-LD 结合使用吗？
Should you Combine Swagger with HATEOAS/HAL/JSON-LD?
我正在为我的 ASP.NET 核心 API 使用 Swashbuckle，它在单独的文档中描述了我的 API 并为所有这些信息提供了一个很好的 UI .
使用像 HATEOAS、HAL 或 JSON-LD 这样的东西结合 Swagger 修改文档本身有什么好处吗？
Here 是将 Swagger 与 HAL 结合使用的示例。
除了使用 Swagger.
之外，将 HATEOAS 集成到您的 API 代码中也有明显的优势
Swagger 为您的 API 添加表单，使它们看起来漂亮且易于呈现，以便可以轻松编写客户端代码，同时它还使文档成为一个不那么无聊的任务将其与代码集成。不用说，如果在编码结束后完成，它还可以节省记录所需的额外时间。从这个意义上来说，还是有点革命性的。
另一方面，HATEOAS 通过启用 Level 3 RMM 让您的 API 可以自我发现。这样可以更轻松地从一个 API 导航到另一个。这个想法是有一个客户端可以使用的基础 URL，其余的 REST API 是从这个基础 URL.
中发现的
现在的问题是，为什么两者都有？好吧，它只是为您的 Restful API 增加了更多维度，并为客户提供了更多选择，而只需很少的编码工作。谁不想这样？
就像 sampada 所说的那样 - swagger 和 HATEOAS - 为你的 api 的不同维度增加了更多价值。
Swagger 将为开发生命周期增加价值，使您的 api 在开发时更易于理解和浏览。
HATEOAS 将在客户使用时为您的 api 增值。
HATEOAS 提供的 link 使您可以 link 您的 api 的不同部分（即：资源），而无需在您的应用程序客户端代码中对这些 link 进行硬编码.
假设您有一份合同以及与之相关的几个文件。
一种非常常见的建模方法是使用两种资源：
- 合同资源 - 为您提供列出、添加、删除、更改合同的操作；
- 文档资源 - 为您提供列出、添加、删除、更改文档的操作
对于 link 这两个，您可以在包含相关资源数组的两个资源模型中添加字段。
此外，您还必须在客户端应用程序中实现这些隐含知识。
这样，随着时间的推移，您（将）给您的资源表示添加混乱，用与其他 objects.
的关系信息污染它
这就是 HATEOAS 发挥作用的地方，它既可以将这些关系信息从您的业务中移出 objects，又可以提供一种统一的方式来处理这些关系。
两种资源业务 objects 现在将包含一个 standardized header 或 value-field 包含有关 all 关系的信息当前资源的。
例如。一个合同资源现在将有 3 links 与 rel-attribute "document" linking 到适当的文档资源和 1 link 与 rel-attribute "order" link根据此合同产生的订单。
据我所知JSON-LD用于规范不同API的词汇表，方便使用他们 side-by-side。
有些人可能会使用 firstName 和 lastName 作为 Person objects 属性，而其他人可能会使用名为 givenName 和 familyName 的属性。
使用 JSON-LD，您可以将两个 objects 映射到一个通用名称。
你可以考虑看看这个 link: DZone - Json-LD
考虑研究 Hydra：
Hydra 是 JSON-LD 的一个词汇表，它允许您将超媒体控件嵌入到您的数据中。此外，您可以提供一个 API 文档端点，其作用与 Swagger 定义类似。我喜欢 Hydra 的地方在于，超媒体控件被嵌入到响应中，而不是在某种服务定义中处于带外状态。 JSON-LD 和 Schema.org 绝对值得研究，因为 Google 和微软都在他们的产品中支持它们。
Hydra 仍然相对较新，因此可用工具不如 Swagger 强大。
我正在为我的 ASP.NET 核心 API 使用 Swashbuckle，它在单独的文档中描述了我的 API 并为所有这些信息提供了一个很好的 UI .
使用像 HATEOAS、HAL 或 JSON-LD 这样的东西结合 Swagger 修改文档本身有什么好处吗？
Here 是将 Swagger 与 HAL 结合使用的示例。
除了使用 Swagger.
HATEOAS 集成到您的 API 代码中也有明显的优势
Swagger 为您的 API 添加表单，使它们看起来漂亮且易于呈现，以便可以轻松编写客户端代码，同时它还使文档成为一个不那么无聊的任务将其与代码集成。不用说，如果在编码结束后完成，它还可以节省记录所需的额外时间。从这个意义上来说，还是有点革命性的。
HATEOAS 通过启用 Level 3 RMM 让您的 API 可以自我发现。这样可以更轻松地从一个 API 导航到另一个。这个想法是有一个客户端可以使用的基础 URL，其余的 REST API 是从这个基础 URL.
现在的问题是，为什么两者都有？好吧，它只是为您的 Restful API 增加了更多维度，并为客户提供了更多选择，而只需很少的编码工作。谁不想这样？
就像 sampada 所说的那样 - swagger 和 HATEOAS - 为你的 api 的不同维度增加了更多价值。
Swagger 将为开发生命周期增加价值，使您的 api 在开发时更易于理解和浏览。
HATEOAS 将在客户使用时为您的 api 增值。 HATEOAS 提供的 link 使您可以 link 您的 api 的不同部分（即：资源），而无需在您的应用程序客户端代码中对这些 link 进行硬编码.
假设您有一份合同以及与之相关的几个文件。 一种非常常见的建模方法是使用两种资源：
- 合同资源 - 为您提供列出、添加、删除、更改合同的操作；
- 文档资源 - 为您提供列出、添加、删除、更改文档的操作
对于 link 这两个，您可以在包含相关资源数组的两个资源模型中添加字段。 此外，您还必须在客户端应用程序中实现这些隐含知识。 这样，随着时间的推移，您（将）给您的资源表示添加混乱，用与其他 objects.
的关系信息污染它这就是 HATEOAS 发挥作用的地方，它既可以将这些关系信息从您的业务中移出 objects，又可以提供一种统一的方式来处理这些关系。 两种资源业务 objects 现在将包含一个 standardized header 或 value-field 包含有关 all 关系的信息当前资源的。 例如。一个合同资源现在将有 3 links 与 rel-attribute "document" linking 到适当的文档资源和 1 link 与 rel-attribute "order" link根据此合同产生的订单。
据我所知JSON-LD用于规范不同API的词汇表，方便使用他们 side-by-side。 有些人可能会使用 firstName 和 lastName 作为 Person objects 属性，而其他人可能会使用名为 givenName 和 familyName 的属性。 使用 JSON-LD，您可以将两个 objects 映射到一个通用名称。 你可以考虑看看这个 link: DZone - Json-LD
考虑研究 Hydra：
Hydra 是 JSON-LD 的一个词汇表，它允许您将超媒体控件嵌入到您的数据中。此外，您可以提供一个 API 文档端点，其作用与 Swagger 定义类似。我喜欢 Hydra 的地方在于，超媒体控件被嵌入到响应中，而不是在某种服务定义中处于带外状态。 JSON-LD 和 Schema.org 绝对值得研究，因为 Google 和微软都在他们的产品中支持它们。
Hydra 仍然相对较新，因此可用工具不如 Swagger 强大。