具有单个端点的多个响应的 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 等于“组”。
因此，问题在于 Swagger 允许通过单个端点(方法和响应代码)仅提供单一响应格式。例如。我们无法为 提供 2 种响应格式/用户 端点“ 200 ”响应代码和 获取 HTTP 方法。

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

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

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

Answer 1

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

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

或者，如果你只需要通过一个参数对用户进行分组——组，你确实可以添加一个额外的资源:/user-groups因为您正在有效地检索 全部 嵌入了用户集合的用户组。