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

我正在开发提供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"
         }
    ]
]

当查询param groupby等于"group" 时,我们提供这样的响应.因此,问题在于Swagger允许通过单个端点(方法和响应代码)仅提供单一响应格式.例如,我们不能为/ users端点" 200 "响应代码和GET HTTP方法提供2种响应格式.

而现在我对如何改变我们的REST设计以使其与Swagger兼容的方式感到困惑.

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

Swagger并不是一个严格的要求,因此任何有关其他REST文档工具的想法都将受到高度赞赏

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

如果要执行RESTful搜索,请将搜索视为自己的资源.缺点是它需要向服务器发出两个请求来获得响应:一个用于创建search对象并返回201,其中包含适当的Location标头和搜索结果的链接,另一个请求检索此搜索的结果.好处是可以与Swagger一起使用,并且您可以重用其他资源的模式.

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