根据 openAPI 中的查询参数指定 RESTful API 响应

Question

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

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

因此，我正在寻找一种根据给定请求的查询参数指定不同 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 参数验证任何给定的响应（例如，"available"不应该是一个字段 when detail=robust）。到目前为止，我还没有找到一种方法来根据查询参数在openAPI中指定不同的返回行为。

有没有办法根据查询参数指定行为？或者，我应该将 API 端点更改为类似的内容/hotels/{hotelId}/{detailLevel}吗？

Answer 1

令我失望的是，我了解到 openAPI不支持使用查询参数来区分具有相同路径的端点。

我将指定我的路径/hotels/{hotelId}/{detailLevel}。