RAML gleiche Methode Überladung Dokumentation

Question

Ich habe 2 PUT Methoden in meinem Rest API mit dem gleichen Einstiegspunkt.

Methode # 1: PUT/videos/{videoId} mit Typ multipart/form-data, die das Video ersetzen wird.

Methode 2: PUT/videos/{videoId}? Title = newTitle & description = newDescription, das den Titel und die Beschreibung des Videos aktualisiert.

Wenn ich versuche, es zu dokumentieren, wie folgende erhalte ich „Methode bereits erklärt:‚setzen‘“

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 

Haben Sie Vorschläge, wie diesen Fall zu dokumentieren?

Danke!

Answer 1

Es ist keine gute Vorgehensweise, die Daten zur Änderung der Abfrageparameter zu senden, wenn eine PUT-Anforderung ausgeführt wird. Statt dessen würde ich Ihre zweite PUT für einen Patch mit einem Content-Type ändern: application/json als die Art des Körpers, und als Inhalt für die Nutzlast würde ich

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

Damit senden, Ihre API würde alles erreichen, was du erreichen willst (soweit ich von deiner Frage komme).

Beachten Sie, dass ich dies für PATCH geändert haben, weil in einem PATCH ist nicht erforderlich, dass Sie das Loch Json mit Daten senden. Sie könnten später nur einen PATCH senden, um die Beschreibung zu ändern, wenn Ihre API-Implementierung dies unterstützt. In einer PUT-Anfrage sollten Sie das Loch json senden.