Документация по перегрузке одного и того же метода RAML

У меня есть 2 метода PUT в моем API отдыха с одной и той же точкой входа.

Способ № 1: ВСТАВЬТЕ /videos/{videoId} с типом multipart/form-data, который заменит видео.

Способ № 2: УСТАНОВИТЕ /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

Есть ли у вас какие-либо предложения о том, как задокументировать этот случай?

Спасибо!


rest raml
person Andrea B    schedule 21.03.2016    source источник
comment
Как говорит @farolfo ниже, существует проблема дизайна. Во всяком случае, описанный выше подход нарушает принцип согласованности: почему одна часть видеообъекта должна быть обновлена ​​параметрами запроса, а другая — объектом multipart/form-data. Просто используйте multipart/form-data для всех случаев: это облегчит работу пользователям вашего API.   -  person David Dossot    schedule 23.03.2016

Ответы (1)


arrow_upward
1
arrow_downward

Не рекомендуется отправлять данные для изменения параметров запроса при выполнении запроса PUT. Вместо этого я бы изменил ваш второй PUT на PATCH с Content-Type: application/json в качестве типа тела и в качестве содержимого для этой полезной нагрузки, которую я бы отправил

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

При этом ваш API достигнет всего, что вы хотите здесь получить (насколько я понимаю из вашего вопроса).

Обратите внимание, что я изменил это для PATCH, потому что PATCH не является обязательным для вас, чтобы отправить json дыры с данными. Позже вы можете отправить PATCH только для изменения описания, если ваша реализация API поддерживает это. В запросе PUT вы должны отправить дыру json.

person farolfo    schedule 22.03.2016
comment
Если вы выбираете PATCH, подумайте о том, чтобы следовать RFC-6902, также известному как JSON Patch jsonpatch.com - person David Dossot; 23.03.2016