提供查询参数时的条件 OpenAPI 请求正文

Question

我为管理食物类型配置了以下端点

• POST ~ /food/types
• 获取 ~ /food/types
• 获取 ~ /food/types/{id}
• PUT ~ /food/types/{id}
• 删除 ~ /food/types/{id}

我试图在我的 REST API 中表示一个克隆操作，并希望避免在我的端点中使用动词。

经过一些研究，我想出了以下内容，因为它符合我能想到的其他解决方案中最符合基本 REST 原则的内容：

POST ~ /food/types?sourceId={id}

这意味着该端点的方法（在典型的 MVC 框架中）需要有条件地处理发送 JSON 有效负载时的创建以及提供查询参数时的资源复制。

我试图思考如何在我的 OpenAPI 规范文档（v3.0.2）中表达这一点

这是我到目前为止所得到的：

/api/food/types:
    post:
      summary: Create a new type of food
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: ./response/food-type.yaml
        '400':
          description: Bad Request
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./request/food-type.yaml
      description: Create a new type of food
      tags:
        - Food Type
    parameters: []

request/food-type.yaml 包含一个带有两个必需参数的对象：

1. 姓名，
2. 类别

   当我的框架根据 OpenAPI 规范验证请求时，我希望它有时忽略请求正文，当且仅当请求参数提供了“sourceId”参数时。

   这种类型的东西甚至可以在 OpenAPI 3+ 中表达，还是我用错了方法？

   简而言之，当使用 OpenAPI 3 在发布请求中提供特定查询参数时，是否可以忽略请求正文。

   在这个问题之后，我的 REST 方法是否缺乏，是否有更好的方法可以表示我的 API 中资源的克隆？

Answer 1

请改用消息正文来描述来源：

POST /food/types {"clone": "{id}"}

如果将它们转换为名词，您甚至可以使用动词：

POST /food/type-cloning {"source": "{id}"