Должен ли я использовать тот же объект в документации OpenAPI POST-запроса и ответа? - PullRequest
Новая
       6

Должен ли я использовать тот же объект в документации OpenAPI POST-запроса и ответа?

0 голосов
/ 13 апреля 2020

Я использую OpenAPI для разработки интерфейсов приложений RESTful. У меня есть запрос на создание нового заказа POST /orders. Допустим, для простоты требуется следующее тело: 

{
    "item" : "product1",
    "quantity" : 20
}

Теперь возвращаемое значение - тот же заказ, но с некоторыми дополнительными полями, вычисленными при создании заказа: 

{
    "businessId" : "someId",
    "item" : "product1",
    "quantity" : 20,
    "someOtherValue" : "IWasCalculatedDuringCreationOfOrder"
}

Вопрос: В определении конечной точки OpenAPI должен ли объект, передаваемый в POST, быть тем же объектом, который был возвращен этим методом? С одной стороны, мы ссылаемся на один и тот же ресурс order REST, так что да, с другой стороны, использование одного и того же dto для запроса и ответа приведет к документации запроса, описывающей поля, которые никогда не будут отправлены (например, businessId).

Было бы просто назвать передаваемый объект, скажем, OrderDTO, но если оба объекта одинаковы, у меня фактически есть поля, которые я не ожидаю, чтобы существовать в описании запроса, например, вызывающая сторона никогда не узнает businessId вновь созданного заказа. По этой причине я подготавливаю отдельные объекты dto для запроса и ответа, но я не уверен, является ли такой подход спокойным и правильным - в конце концов мы ссылаемся на один order ресурс здесь.

...