Как описать единый формат ответов REST API для всех в Swagger OpenAPI3?

Question

[Виталий Хоменко]

Есть множество контроллеров, все они отдают ответ в едином формате:

{
  "response": true, # true/false
  "error": {
    "code": 0, # 0 или код ошибки
    "message": "" # текст ошибки
  },
  "data": null # null или данные ответа
}

Все модели форм запросов, ответов, заголовки и пр. вынесены в компоненты и подключаются по $ref

Но не получается совместить единый для всех формат ответов с данными ответа. Вот пример:

paths:
  /system/banner/{position}:
    get:
      # ...
      parameters:
        - name: position
          # ...
      responses:
        200:
          description: OK
          headers:
            # ...
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/responses/CommonResponse' # <-- Единый формат ответа
                  - properties: <-- # Он должен быть дополнен данными
                      data:
                        $ref: '#/components/schemas/BannerList'
        400:
          # ...

В результате сваггер генерирует вот такое:

{
  "data": [
    {
      "id": 0,
      "title": "string",
      "content": "string",
      "date_created": "2019-08-07T10:54:38.215Z",
      "date_edited": "2019-08-07T10:54:38.215Z"
    }
  ]
}

а нужно вот так:

{
  "response": true,
  "error": {
    "code": 0,
    "message": ""
  },
  "data": [
    {
      "id": 0,
      "title": "string",
      "content": "string",
      "date_created": "2019-08-07T10:54:38.215Z",
      "date_edited": "2019-08-07T10:54:38.215Z"
    }
  ]
}

Что я делаю не так?

Answer 1

[davidnum95]

properties должно быть на одном уровне с allOf, вот так:

allOf:
   - $ref: '#/components/responses/CommonResponse' # <-- Единый формат ответа
properties: <-- # Он должен быть дополнен данными
   data:
      $ref: '#/components/schemas/BannerList'

Comments

[Виталий Хоменко]

Увы, не работает. Парсится без ошибок, но результат такой же, как и у меня.

[davidnum95]

Виталий Хоменко, странно, у меня работает, попробуйте схему вынести в отдельный объект

[Виталий Хоменко]

davidnum95, я нашел причину. У меня один объект в responses, а второй в schemas. И они не мерджатся
Если перенести CommonResponse с responses в schemas, то начинает работать.

content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - properties:
                      data:
                        $ref: '#/components/schemas/BannerList'

Спасибо! Отмечу решением

Answer 2

[Иван Шумов]

Ручками. Ты же в курсе что это не REST, правда?

Comments

[Виталий Хоменко]

Это не имеет значения. Нужно сократить описание в Сваггере, совмещать две схемы - общую и конкретные данные

[Иван Шумов]

Виталий Хоменко, там можно сделать вложенные связи, но не наоборот, так что не получится. Но не называй это REST, пожалуйста - для техлида и при стаже в 9 лет должно быть стыдно

[mamontm]

Ручками

Серьезно?

Ты же в курсе что это не REST, правда?

Если ты чего-то не знаешь, то можно просто промолчать, умные слова тебя не спасут.

[Иван Шумов]

mamontm, если знаешь как это сделать то пример в студию) ну и, пожалуйста, аргументы за то что это REST.

[davidnum95]

Иван Шумов, чому не рест то? Базовый набор принципов реста соблюдается вроде как.

[Виталий Хоменко]

Давайте не затрагивать REST, ок? Пусть это будет просто API. Суть вопроса от этого не изменится.

Нужно сократить кол-во ручной работы при описании API. Описывать каждый ответ руками не вариант, я все же надеюсь, что я что-то не так сделал и данные с общим форматом ответа как-то можно мерджить.

[Иван Шумов]

Виталий Хоменко, максимум что могу предложить - каждый ключ верхнего уровня описать как отдельную модель и линковать. таким образом можно немного упростить, но это максимум

[Иван Шумов]

davidnum95, тем что в HTTP REST представление должно содержать только объект, а все остальное должно находиться в мета-информации: то есть в теле ответа только стейт объекта, а все остальное в http headers. кроме того ошибки могут существовать только в виде ответа при не 2хх ответе. часть ответа response: bool вообще намекает на двойственность

[Виталий Хоменко]

Иван Шумов, данные ошибки дублируются в теле ответа по определенным причинам: не все клиенты могут нормально работать с не 200 статусами ответов. Потому у нас данные дублируются и режимы могут меняться. По умолчанию HTTP коды: 200 - ОК, а если ошибка, то 400, 401, 403 и т.д. по ситуации.

[Иван Шумов]

Виталий Хоменко, в смысле не все клиенты? люди или роботы?) если люди то я им могу только посочувствовать, а роботы могут

[Виталий Хоменко]

Иван Шумов, были случаи, когда разработчики клиента под API просили всегда отдавать двухсотый, а код ошибки и сообщение возвращать в теле ответа. Такое было и с JS, и даже с мобильными приложениями(Джава, не уверен). Если с JS еще понятно - вопрос квалификации, то с мобильными разработчиками совсем непонятно почему: старая библиотека или фреймворк? Не спрашивайте, не знаю.

[Иван Шумов]

Виталий Хоменко, это всегда низкая квалификация. Но если по делу - там ниже Давид ответил вариант, который поможет, но по мне так если оно и работает то дикость и не читабельность

[Виталий Хоменко]

Иван Шумов, спасибо!