RAML 同方法重载文档

Question

我的 REST API 中有 2 个 PUT 方法具有相同的入口点。

方法 #1：使用 multipart/form-data 类型的 PUT /videos/{videoId} 替换视频。

方法 #2：PUT /videos/{videoId}?title=newTitle&description=newDescription 将更新视频的标题和说明。

当我尝试像下面这样记录它时，我得到“方法已经声明：'put'”

put:
  description: replace a video with a new video
  body:
    multipart/form-data:
      formParameters:
          file: 
            description: a video file to replace the current video file
            required: true
            type: file
  responses:
    200:
        body:
          application/json:
            schema: !include video.schema
            example: !include video.example
        description: Returns the video object.
put:
  description: update video's fields
  queryParameters:
    title:
      description: video's title
      required: false
      type: string
    description:
      description: video's description
      required: false
      type: string
  responses:
    200:
      body:
        application/json:
          schema: !include video.schema
          example: !include video.example

您对如何记录这个案例有什么建议吗？

谢谢！

Answer 1

在执行 PUT 请求时发送数据以更改查询参数不是一个好习惯。相反，我会将您的第二个 PUT 更改为带有 Content-Type: application/json 作为正文类型的 PATCH，并作为该有效负载的内容，我将发送

{ title: "newTitle", description: "newDescription" }

有了这个，你的 API 将实现你想要的一切（据我从你的问题中得到的）。

请注意，我为 PATCH 更改了此设置，因为在 PATCH 中，您不必强制发送带有数据的洞 json。如果您的 API 实现支持，您以后可能只发送一个 PATCH 来更改描述。在 PUT 请求中，您应该发送洞 json。