用于指定不同响应模型的API设计模式_Api_Swagger_Api Design

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

api swagger

用于指定不同响应模型的API设计模式,api,swagger,api-design,Api,Swagger,Api Design,我正在尝试粗略设计一个用于返回文章内容的api。能够具体说明我们是想要整篇文章、一个摘要，还是该内容的其他变体，似乎很有价值我的直觉是在GET请求中添加一个查询参数，比如dataModel（可以随意建议更好的名称）。例如，summary可能只是id、title和description，而list可能返回id、title、author和lastModifiedDate /v0/articles/{id} /v0/articles/{id}？数据模型=摘要 /v0/articles/{id}？数

我正在尝试粗略设计一个用于返回文章内容的api。能够具体说明我们是想要整篇文章、一个摘要，还是该内容的其他变体，似乎很有价值

我的直觉是在GET请求中添加一个查询参数，比如

dataModel

（可以随意建议更好的名称）。例如，

summary

可能只是id、title和description，而

list

可能返回id、title、author和lastModifiedDate

/v0/articles/{id}
/v0/articles/{id}？数据模型=摘要
/v0/articles/{id}？数据模型=列表

但是，我们使用Swagger进行文档编制，Swagger似乎不支持基于查询参数（）返回不同的对象。因此，我想知道是否还有其他已建立的模式也同样可以接受？

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

/v0/articles/{id}
/v0/articles/{id}/summary（返回带有id、title和description的模型）
/v0/articles/{id}/list（返回带有id、title、author和lastModifiedDate的模型）

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

/v0/articles/{id}
/v0/articles/{id}/summary（返回带有id、title和description的模型）
/v0/articles/{id}/list（返回带有id、title、author和lastModifiedDate的模型）

使用Swagger的正确解决方案是创建一个包含所有数据模型的公共属性的返回类型。然后，您可以建模一个

鉴别器

，并使用

allOf

构造来创建正确的响应类型

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

您将看到如何使用

Animal

返回类型，以及

Cat

和

Dog

具体类型来完成此操作。