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

Question

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

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

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

Answer 1

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

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那样强大.