Код-ревью Senior REST API и OpenAPI обновлено
Ревью фрагмента OpenAPI
Вопрос
Фрагмент OpenAPI для регистрации клиента. Найди проблемы.
paths:
/users:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
email: { type: string }
password: { type: string }
birthDate: { type: string }
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id: { type: integer }
password: { type: string }
Коротко
Хорошая схема: required: [email, password], email с format: email и maxLength, birthDate с format: date, ответ 201 с id и без пароля, описанные ошибки 400 и 409 в едином формате, лимиты на регистрацию.
Что должен найти ревьюер
- Ошибкастрока 8Нет списка required: непонятно, какие поля обязательны
- Стильстрока 10email без format: email и ограничений длины: валидация остаётся на догадку
- Ошибкастрока 12birthDate без format: date: клиенты пришлют дату в разных форматах
- Ошибкастрока 14Создание ресурса принято отдавать с 201, и нет описания ошибок 400/409 (email занят)
- Безопасностьстрока 21Пароль возвращается в ответе: утечка чувствительных данных
- Безопасностьстрока 3Нет описания security и ограничений частоты для публичной регистрации
Разбор
Хорошая схема: required: [email, password], email с format: email и maxLength, birthDate с format: date, ответ 201 с id и без пароля, описанные ошибки 400 и 409 в едином формате, лимиты на регистрацию.
Ответьте сами, а не прочитайте
В тренажёре вопрос попадёт в повторения и вернётся, когда начнёт забываться. Плюс билеты с зачётом: 20 вопросов, не больше 2 ошибок.