为同一端点/路径定义多个2xx响应

Question

我们有一个GET端点，它并不总是返回数据，其思想是定义两个2xx响应:

1. 如果我们有一些数据，那么我们返回一个带有响应体的200代码。
2. 如果我们没有任何数据，那么我们返回一个204代码，没有响应体。

"paths": {
"/my-endpoint/": {
"get":  {
"operationId": "myOperation",
"responses:": {
"200": {
"description": "OK with body",
"content": {
"application/json": {
"schema":{
"$ref": "#/components/schemas/MyResponse"
}
}
}
},
"204": {
"description": "OK"
}
}
....

这是可能的/允许的吗?这种用例的最佳实践是什么?

Answer 1

如果这两种情况(有数据和没有数据)都意味着是一个标准的业务场景那么我同意你的设计。

200年和204年消费者的反应是很直接的,如果你添加适当的文档,API设计好了;此外，如果您在api中始终使用此模式，

这种设计的最终批准只能通过了解资源、其目的和业务用例来完成。