具有单个端点的多个响应的 RESTful 设计

Question

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

所以，我们有一个带有“/users”资源的 REST，默认情况下，它会按照 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

正如您正确指出的那样，您在两个用例中返回了两种不同的格式（表示）。未分组的用户作为用户数组（集合）返回。当您附加 groupBy 查询参数时，您会返回完全不同的内容 - 一组搜索结果。

如果您想进行 RESTful 搜索，请将搜索视为自己的资源。缺点是它需要向服务器发出两个请求才能获得响应：一个创建search 对象并返回一个带有适当Location 标头和搜索结果链接的201，另一个请求检索结果对于这个搜索。好处是它将与 Swagger 一起使用，并且您可以将该模式重用于其他资源。

或者，如果您只需要通过 one 参数对用户进行分组 - 组，您确实可以添加一个额外的资源：@​​987654324@，因为您正在有效地检索 all 组嵌入了用户集合的用户。