基于查询参数在openAPI中指定RESTful API响应

Question

我正在设计一个项目的openAPI规范。该项目是一个REST API，提供有关酒店的信息。

我希望提供有关酒店的详细信息或快速摘要。我的理解是，由于这两者都涉及到我的数据存储中的同一个对象，因此我应该使用查询参数来请求不同的数据类型。

因此，我正在寻找一种基于给定请求的查询参数指定不同API行为的方法。这是我的当前实现。我正在查看这样的端点：

/hotels/{hotelId}?detail={detailLevel}

其中 {hotelId} 是整数，{detailLevel} 是一个可选的字符串枚举，可以是 summary 或 robust。

如果 detail=robust，响应应该大致如下：

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip"
  "streetAddress": "2650 Las Vegas Blvd S",
  "city": "Las Vegas",
  "state": "NV",
  "zipCode": 89109
  "rating": 4.4,
  "minimumPrice": 125,
  "availableRooms": 10,
}

如果detail=summary，响应的结果应该类似于这样：

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip",
  "rating": 4,
  "zipCode": 89109,
  "available": true
}

我不希望有一个规范来涵盖这两种响应，因为我希望通过其URL参数轻松验证任何给定的响应（例如，当detail=robust时，"available"不应该是一个字段）。目前为止，我还没有找到一种基于查询参数在openAPI中指定不同返回行为的方法。

是否有一种根据查询参数指定行为的方法？或者，我应该将我的API端点更改为类似/hotels/{hotelId}/{detailLevel}的形式吗？

- Taycan

---

我不确定，MatrixVariables 会有任何用处吗？ - raj240

Answer 1

很遗憾，我得知openAPI 不支持使用查询参数来区分相同路径的端点。

相反，我将指定我的路径为/hotels/{hotelId}/{detailLevel}。

- Taycan

---

不错的参考。顺便提一下，我也有同样的问题，有时候我觉得我需要使用GraphQL而不是RESTful API。但是我也不确定。 - Kasir Barati