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的要求之一是按“组”字段对用户进行分组，并提供以下格式的响应：

[
    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对象并返回201，其中包含相应的Location标题和搜索结果的链接，另一个请求检索此搜索的结果。好处是可以与Swagger一起使用，并且您可以重用其他资源的模式。

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

针对具有单个端点

1 个答案: