用于指定不同响应模型的 API 设计模式答案

【问题标题】：API design pattern for specifying different response models用于指定不同响应模型的 API 设计模式
【发布时间】：2016-01-07 16:16:28
【问题描述】：

我正在尝试制作一个用于返回文章内容的 api。能够指定我们是想要整篇文章、摘要还是该内容的其他变体似乎很有价值。

我的直觉是向 GET 请求添加一个查询参数，例如 dataModel（请随意建议更好的名称）。例如，默认可能是整篇文章，但summary 可能只是 id、title 和 description，而list 可能返回 id、title、author 和 lastModifiedDate。

但是，我们将 Swagger 用于文档，并且 Swagger 似乎不支持根据查询参数返回不同的对象 (see this)。所以我想知道是否还有其他同样可以接受的既定模式？

【问题讨论】：

【解决方案1】：

使用 Swagger 的正确解决方案是创建一个包含所有数据模型的通用属性的返回类型。然后，您可以为 discriminator 建模并使用 allOf 构造来创建正确的响应类型。

如果您在此处查看示例定义：

您将看到如何使用Animal 返回类型以及Cat 和Dog 具体类型来完成。

【讨论】：

【解决方案2】：

一种解决方法是对 dataModel 使用路径变量而不是 URL 查询字符串，并改用以下路由

【讨论】：