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

У меня есть два метода PUT в моем API-интерфейсе останова с той же точкой входа.RAML такой же метод перегрузки документации

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

Метод № 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

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

Спасибо!

источник

2016-03-21 Andrea B

Как говорит @farolfo, это проблема с дизайном. Во всяком случае, вышеупомянутый подход нарушает принцип согласованности: почему часть части видеообъекта должна быть обновлена параметрами запроса, а другие - с объектом multipart/form-data. Просто используйте multipart/form-data для всех случаев: это упростит работу ваших пользователей API. –

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

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

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

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

источник

2016-03-22 18:47:31 farolfo

Если вы идете на 'PATCH', рассмотрите следующий RFC-6902, а также JSON Patch http://jsonpatch.com/ –

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

ответ

Смежные вопросы