Skip to content

422_200_fix.md

Latest commit

 

History

History
286 lines (237 loc) · 10.1 KB

422_200_fix.md

File metadata and controls

286 lines (237 loc) · 10.1 KB

План исправления 422 и 200 ответов в OpenAPI

Проблема

Все ответы 422 используют общий UnprocessableEntity с неуместным примером про пароль ("Password must be at least 6 characters"), который не релевантен для большинства эндпоинтов.

Решение

Создать контекстные примеры для каждого эндпоинта или группы эндпоинтов.

Исправление 200 ответов

  • /dictionary/user/statuses — заменить name: "John Doe" на реальные статусы (New, Active, Blocked, Unconfirmed)

Исправление 422 ответов по модулям

Users.Operations

  • GET /user/user/index — ошибки фильтров (UserSearch)

    КОД: actionIndex() → $searchModel->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: page, status, groupIds, courseIds
ПРИМЕРЫ: "Page must be number"
❌ ПРОБЛЕМА: responses.yaml показывает пример про "Password must be at least 6 characters"
          Пароль НИКОГДА не валидируется в GET методах!
✓ ИСПРАВЛЕНИЕ: Заменить пример на ошибки фильтрации (page, status)

  • GET /user/user/admin — ошибки фильтров (AdminSearch)

    КОД: actionAdmin() → $searchModel->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: page, sort
ПРИМЕРЫ: "Page must be number"
❌ ПРОБЛЕМА: responses.yaml показывает пример про пароль
          Пароль НИКОГДА не валидируется!
✓ ИСПРАВЛЕНИЕ: Заменить пример на ошибки фильтрации

  • POST /user/user/create — валидация UserForm

    КОД: actionCreate() → $model->validate() → $model->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: username, email, password, role
ПРИМЕРЫ:
  - username: "Username cannot be blank", "Username must contain at least 2 characters"
  - email: "Email cannot be blank", "Email must be a valid email address"
  - password: "Password must be at least 6 characters"
  - role: "The role does not exist"
✅ ПАРОЛЬ УМЕСТЕН здесь! responses.yaml пример подходит

  • PUT /user/user/update — валидация UserForm

    КОД: actionUpdate() → $model->validate() → $model->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: email, role (пароль опционален)
ПРИМЕРЫ:
  - email: "Email must be a valid email address"
  - role: "The role does not exist"
❌ ПРОБЛЕМА: responses.yaml показывает пример про пароль
          При обновлении пароль не всегда валидируется
✓ ИСПРАВЛЕНИЕ: Заменить пример на ошибки email/role

Users.Courses

  • POST /user/user/add-course — назначение курса (AddCourseForm)

    КОД: actionAddCourse() → $form->validate() → $form->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: userIds, courseIds
ПРИМЕРЫ:
  - userIds: "userIds должен быть массив"
  - courseIds: "courseIds должен быть массив", "В courseIds указан не верный ИД"
❌ ПРОБЛЕМА: responses.yaml показывает пример про пароль
          Пароль НИКОГДА не валидируется в этой форме!
✓ ИСПРАВЛЕНИЕ: Заменить пример на ошибки массивов (userIds, courseIds)

  • POST /user/user/delete-course — отзыв курса (AddCourseForm)

    КОД: actionDeleteCourse() → $form->validate() → $form->getFirstErrors()
РЕАЛЬНЫЕ ОШИБКИ: userIds, courseIds (те же, что и add-course)
ПРИМЕРЫ:
  - userIds: "userIds должен быть массив"
  - courseIds: "courseIds должен быть массив"
❌ ПРОБЛЕМА: responses.yaml показывает пример про пароль
          Пароль НИКОГДА не валидируется!
✓ ИСПРАВЛЕНИЕ: Заменить пример на ошибки массивов

Users.Import

  • POST /user/user/load — импорт пользователей

    errors:
  fileImport:
    - "Файл не загружен"
    - "Неподдерживаемый формат файла"

  • GET /user/import-report/index — история импортов

    errors:
  page:
    - "Некорректный номер страницы"

Groups.Structure

  • GET /group/group/index — список групп

    errors:
  page:
    - "Номер страницы должен быть положительным числом"

  • POST /group/group/create — создание группы

    errors:
  name:
    - "Название группы обязательно"
    - "Группа с таким названием уже существует"
  parent_id:
    - "Родительская группа не найдена"

  • PUT /group/group/update — обновление группы

    errors:
  id:
    - "Группа не найдена"
  name:
    - "Название группы обязательно"
  parent_id:
    - "Нельзя переместить группу в её дочернюю группу"

  • DELETE /group/group/delete — удаление групп

    errors:
  ids:
    - "Не указаны ID групп для удаления"

  • POST /group/group/add-user — добавление пользователя

    errors:
  user_id:
    - "Пользователь не найден"
  group_id:
    - "Группа не найдена"

  • POST /group/group/move-user — перемещение пользователя

    errors:
  user_id:
    - "Пользователь не найден"
  from_group_id:
    - "Исходная группа не найдена"
  to_group_id:
    - "Целевая группа не найдена"

  • POST /group/group/assign-courses — назначение курсов группе

    errors:
  group_id:
    - "Группа не найдена"
  course_ids:
    - "Курс не найден"

Certificates.Issued

  • GET /certificate/certificate/index — список сертификатов

    errors:
  page:
    - "Некорректный номер страницы"

  • POST /certificate/certificate/create — выдача сертификата

    errors:
  user_id:
    - "Пользователь не найден"
  template_id:
    - "Шаблон сертификата не найден"
  course_id:
    - "Курс не найден"

  • POST /certificate/certificate/export-zip — экспорт в ZIP

    errors:
  ids:
    - "Не указаны ID сертификатов"

Certificates.Templates

  • GET /certificate/template/index — список шаблонов

    errors:
  page:
    - "Некорректный номер страницы"

  • POST /certificate/template/create — создание шаблона

    errors:
  name:
    - "Название шаблона обязательно"
  type:
    - "Некорректный тип сертификата"

Certificate.CustomFields

  • GET /certificate/template-field/index — поля шаблона

    errors:
  template_id:
    - "Шаблон не найден"

  • POST /certificate/template-field/create — создание поля

    errors:
  name:
    - "Название поля обязательно"
  template_id:
    - "Шаблон не найден"

Courses

  • GET /course/course/index — список курсов 
    errors:
  page:
    - "Некорректный номер страницы"

Варианты реализации

Вариант 1: Inline examples (рекомендуется)

Добавить example напрямую в каждый эндпоинт вместо ссылки на общий UnprocessableEntity.

Вариант 2: Несколько шаблонов ошибок

Создать разные response schemas:

  • ValidationErrorUser
  • ValidationErrorGroup
  • ValidationErrorCertificate
  • и т.д.

Вариант 3: Обновить общий UnprocessableEntity

Использовать более универсальный пример:

errors:
  field_name:
    - "Значение поля некорректно"

Приоритет

  1. Высокий: /dictionary/user/statuses (200) — явная ошибка
  2. Высокий: /user/user/create, /user/user/update — часто используются
  3. Средний: Groups, Certificates — важные модули
  4. Низкий: GET-методы с пагинацией — редко возвращают 422

Файлы для изменения

  • openapi-publish/specs/core/common/responses.yaml — общие ответы
  • openapi-publish/specs/users.yaml — модуль пользователей
  • openapi-publish/specs/groups.yaml — модуль групп (если есть)
  • openapi-publish/specs/certificates.yaml — модуль сертификатов (если есть)
  • openapi-publish/specs/learning.yaml — модуль курсов (если есть)
  • openapi-publish/space-platform-api.yaml — собранный файл