我使用Swagger为我的ASP.NET核心API使用Swashbuckle，它在一个单独的文档中描述了我的API，并为所有这些信息提供了一个很好的UI。
使用HATEOAS，HAL或JSON-LD之类的东西是否有任何优点可以与Swagger一起修改文档本身？
Here是使用Swagger和HAL的人的一个例子。
答案 0 :(得分：11)
除了使用HATEOAS之外，将Swagger集成到您的API代码中也有一定的优势。
Swagger通过使表单看起来很好且易于呈现来为您的API添加表单，以便可以轻松编写客户端代码，同时通过将文档与代码集成使文档成为一项不那么无聊的任务。不用说，它还节省了在编码结束后完成文档所需的额外时间。从这个意义上说，它有点革命性。
HATEOAS通过启用Level 3 RMM 使您的API可自行发现。这样可以更轻松地将一个API导航到另一个API。我们的想法是拥有一个客户端可以使用的基本URL，并从该基本URL发现其余的REST API。
现在问题是，为什么两者兼而有之？好吧，它只是为您的Restful API添加了更多维度，并为客户提供了更少的编码工作选择。谁不想要那个？
答案 1 :(得分：11)
就像桑帕达所说 - swagger和HATEOAS - 为你的api的不同维度增加了更多的价值。
Swagger 将为开发生命周期增加价值，使您的api在开发时更易理解和可浏览。
HATEOAS 会在客户端使用时为您的api增加价值。 HATEOAS提供的链接使您可以链接api的不同部分（即：资源），而无需在应用客户端代码中对这些链接进行硬编码。
假设您与一些与之相关的文件签订了合同。 一种非常常见的模拟方法是使用两种资源：
要将这两者链接在一起，您可以在包含相关资源数组的两个资源模型中添加字段。 此外，您还必须在客户端应用程序中实现这些隐式知识。 通过这种方式，您（将）会随着时间的推移为您的资源表示添加混乱，并使用有关与其他对象的关系的信息进行污染。
这就是HATEOAS发挥作用的地方，既可以将业务信息从业务对象中移出，也可以提供统一的方式来处理这些关系。 现在，两个资源业务对象都将包含一个标准化标头或值字段，其中包含有关当前资源的所有关系的信息。 例如。一个合同资源现在有3个链接，其中包含rel-attribute＆＃34; document＆＃34;链接到相应的文档资源和1个链接与rel-attribute＆＃34; order＆＃34;链接到此合同产生的订单。
据我所知， JSON-LD 用于规范化不同API的词汇表，使其更容易并排使用。 有些人可能会使用firstName＆amp; lastName作为Person对象属性，而其他人则有一个名为givenName＆amp;的属性。姓。 使用JSON-LD，您可以将两个对象映射到通用名称。 您可以考虑查看此链接：DZone - Json-LD
答案 2 :(得分：6)
考虑一下Hydra：
Hydra是JSON-LD的词汇表，允许您将超媒体控件嵌入到数据中。此外，您可以提供API文档端点与Swagger定义类似的角色。我喜欢Hydra的是，超媒体控件被烘焙到响应中，而不是某种服务定义中的带外。 JSON-LD和Schema.org绝对值得研究，因为谷歌和微软都在他们的产品中支持它们。
Hydra仍然相对较新，因此可用的工具并不像Swagger那样强大。