rest - REST API 建模中的继承和多态性

Question

我有一个想要通过 REST API 公开的对象层次结构，并且我想讨论最佳实践。我以前看过这个问题(例如 here at the end ， here ， here ，尤其是 here )，但从未真正得出任何结论。

假设我有一个基类，比如 Animal ，以及许多不同的继承类，比如 Antelope , Bird , ..., Zebra .每种动物都有独特的属性。

哪个更好？

一个端点路径，/animals .根据种类，您发送和接收的 body 略有不同。有一个type帮助解析的字段。

每种动物都有一个单独的端点路径，/animals/antelopes , /animals/birds , ..., /animals/zebras .每个端点将始终接受并返回一致的主体(但这些主体将彼此不同)。

Answer 1

OpenAPI 3.0(以前的 Swagger)真正支持 JSON 中的多态性。

从 JSON 模式 v1.0 开始，可以使用 oneOf、allOf、anyOf 等关键字组合模式并获得经过验证的消息有效负载。

https://spacetelescope.github.io/understanding-json-schema/reference/combining.html

但是，关键字 增强了 Swagger 中的模式组合。鉴别器 (v2.0+) 和 一个 (v3.0+) 支持继承和多态。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaComposition

我提供了一个多态 POST 方法的示例 here .