RESTful 单端点多重响应设计

Question

我正在从事提供 REST API 的项目。最近我们决定将它与 Swagger 集成，为每个端点创建详细的文档。几乎所有 REST 都已成功集成，但对于其中一些我们遇到的困难很少。

因此，我们有一个带有“/users”资源的 REST，默认情况下 returns 按给定标准 JSON 格式的用户列表，例如:

[
{
    name: "user1",
    age: 50,
    group: "group1"
},
{
    name: "user2",
    age: 30,
    group: "group2"
},
{
    name: "user3",
    age: 20,
    group: "group1"
}
]

此 REST 的要求之一是按“group”字段对用户进行分组，并提供以下格式的响应：

[
    group1: [ 
        {
            name: "user1",
            age: 50,
            group: "group1"
        },
        {
            name: "user3",
            age: 20,
            group: "group1"
        }]
    group2: [
        {
            name: "user2",
            age: 30,
            group: "group2"
         }
    ]
]

当查询参数 groupby 等于 "group" 时，我们提供这样的响应。因此，问题在于 Swagger 只允许通过单个端点（方法和响应代码）提供单一响应格式。例如。我们无法为 /users 端点“200”响应代码和 GET HTTP 提供 2 种响应格式方法。

现在我对如何更改我们的 REST 设计以使其与 Swagger 兼容的方式感到非常困惑。

备注： 根据 REST 设计原则，为分组用户添加新端点似乎是不正确的分组用户不是单独的资源，而只是现有资源的附加表示。

Swagger 不是一个严格的要求，所以任何关于其他 REST 文档工具的想法都将受到高度赞赏

Answer 1

正如您正确指出的那样，您 return 在两个用例中使用了两种不同的格式（表示）。未分组的用户被 return 编辑为用户数组 (collection)。当您附加 groupBy 查询参数时，您会 return 完全不同的东西 - 一组 搜索结果 .

如果您想进行 RESTful 搜索，请将搜索视为其自身的资源。缺点是它需要向服务器发出两次请求才能获得响应：一个创建 search object 和 return 一个带有适当 Location [=27] 的 201 =] 和 link 搜索结果，另一个请求检索此搜索的结果。好处是它将与 Swagger 一起工作，并且您可以为其他资源重用该模式。

或者，如果您只需要按一个参数对用户进行分组 - 组，您确实可以添加一个额外的资源：/user-groups 因为您正在有效地检索所有个用户组，其中嵌入了 collection 个用户。

RESTful 单端点多重响应设计

RESTful design for multiple responses with single endpoint

rest

design-principles

swagger