iiifx
@iiifx
PHP, OOP, SOLID, Yii2, Composer, PHPStorm

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

Есть множество контроллеров, все они отдают ответ в едином формате:
{
  "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"
    }
  ]
}


Что я делаю не так?
  • Вопрос задан
  • 351 просмотр
Решения вопроса 1
@davidnum95
properties должно быть на одном уровне с allOf, вот так:
allOf:
   - $ref: '#/components/responses/CommonResponse' # <-- Единый формат ответа
properties: <-- # Он должен быть дополнен данными
   data:
      $ref: '#/components/schemas/BannerList'
Ответ написан
Пригласить эксперта
Ответы на вопрос 1
inoise
@inoise
Solution Architect, AWS Certified, Serverless
Ручками. Ты же в курсе что это не REST, правда?
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы