RAML同じメソッドオーバーロードのドキュメント

Question

私は同じエントリーポイントを持つ残りのAPIに2つのPUTメソッドを持っています。

方法1：ビデオを置き換えるmultipart/form-dataタイプのPUT/videos/{videoId}。

方法2：PUT/videos/{videoId}？title = newTitle & description =ビデオのタイトルと説明を更新するnewDescription。

私は次のようにそれを文書化しようとすると、私が得る「方法はすでに宣言： 『置く』」

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リクエストを実行するときに、クエリパラメータでデータを変更して送信することをお勧めしません。その代わりに私は、Content-TypeのでPATCHのために2番目のPUTを変更したい：体の種類としてアプリケーション/ JSONをし、そのペイロードのコンテンツとして、私はこれで

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

を送信したい、あなたのAPIは、私があなたの質問から得る限り、ここに到達したいすべてを達成するでしょう。

私はこれをPATCHのために変更したことに注意してください.PATCHの原因は、データで穴jsonを送信するために必須ではありません。 API実装がこれをサポートしている場合は、後で説明を変更するためにPATCHを送信することがあります。 PUTリクエストでは、ホールjsonを送信する必要があります。