Лабораторная работа VIII. REST API, FOSRestBundle, сериализация и OpenAPI

REST API, медиа-контент и выбор фреймворка

Лабораторная работа 8. REST API, FOSRestBundle, сериализация и OpenAPI

Аудиторная работа: 3 ак. ч.
Самостоятельная работа: 4 ак. ч.

Цель: создать документированный REST API BizFlow.

FOSRestBundle предназначен для разработки RESTful API в Symfony и поддерживает View layer, negotiation, сериализацию и обработку ошибок; актуальная ветка поддерживает современные версии Symfony. [22] NelmioApiDocBundle генерирует OpenAPI-документацию и поддерживает Symfony routes, PHP attributes, FOSRestBundle и Symfony Serializer. [23]

Задание

1. Установите:

composer require friendsofsymfony/rest-bundle
composer require nelmio/api-doc-bundle

1. Убедитесь, что Symfony Serializer включен.

2. Настройте JSON как основной формат API.

3. Все API-маршруты разместите под:

/api

1. Реализуйте:

GET /api/customers
GET /api/customers/{id}
POST /api/customers
PATCH /api/customers/{id}

GET /api/orders
GET /api/orders/{id}
POST /api/orders
PATCH /api/orders/{id}/status

GET /api/products
GET /api/products/{id}

1. Формат ответа списка:

{
"data": [],
"meta": {
"page": 1,
"limit": 20,
"total": 0
}
}

1. Реализуйте query parameters:

page
limit
search
status
sort

1. Ограничьте:

1 <= limit <= 100

1. Создайте DTO для входных данных API.

2. Не передавайте JSON непосредственно в Entity без контроля полей.

3. Используйте Validator.

4. Настройте serialization groups.

5. Скрывайте:

password
внутренние технические поля
секреты

1. Используйте HTTP-коды:

200 OK
201 Created
204 No Content
400 Bad Request
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Content

1. После POST /api/orders возвращайте идентификатор созданного ресурса.

2. Реализуйте единый JSON-формат ошибок:

{
"type": "...",
"title": "...",
"status": 422,
"detail": "...",
"errors": []
}

1. Не возвращайте stack trace в production-ответах.

2. Используйте FOSRestBundle минимум для одного из механизмов:

View;
format handling;
exception handling;
response serialization.

1. Настройте NelmioApiDocBundle.

2. Для каждого endpoint документируйте:

summary;
parameters;
requestBody;
response;
HTTP codes;
security.

1. Добавьте OpenAPI-схемы:

Customer
CreateCustomerRequest
SalesOrder
CreateOrderRequest
ApiError

1. Откройте Swagger/OpenAPI UI.

2. Проверьте все методы вручную.

3. Напишите API functional tests.

Symfony BrowserKit предоставляет jsonRequest() для выполнения JSON-запросов в функциональных тестах. [24]

1. Минимальное количество API-тестов:

15

1. Обязательные негативные тесты:

несуществующий ID;
невалидный email;
пустое имя;
неизвестный status;
limit=100000;
недопустимое изменение статуса;
доступ без требуемой роли;
duplicate email.

Обязательный запрос ИИ API-архитектору

Ты — REST API architect.

Проанализируй BizFlow и спроектируй API для:
customers;
products;
orders.

Требования:
RESTful URLs;
корректные HTTP methods;
корректные status codes;
pagination;
filtering;
DTO;
validation;
serialization groups;
единый error format;
OpenAPI.

Сначала создай контракт API в виде таблицы endpoint/method/request/response/status.
Код пока не пиши.

Обязательный запрос ИИ adversarial tester

Ты — adversarial API tester.

Проанализируй /api.

Создай негативные тесты:
пустой JSON;
сломанный JSON;
лишние поля;
wrong content-type;
несуществующие ID;
duplicate values;
очень большие limit;
отрицательная page;
некорректный enum;
неразрешенные операции;
нарушение последовательности статусов.

После этого запусти тесты и составь список найденных ошибок.

Самопроверка

php bin/console debug:router
php bin/console debug:config fos_rest
php bin/console debug:config nelmio_api_doc
php bin/phpunit

Критерии приемки

[ ] установлен FOSRestBundle
[ ] установлен NelmioApiDocBundle
[ ] API возвращает JSON
[ ] реализованы DTO
[ ] работает validation
[ ] используются serialization groups
[ ] реализованы корректные HTTP status codes
[ ] создан единый error format
[ ] работает OpenAPI
[ ] Swagger UI открывается
[ ] имеется минимум 15 API tests
[ ] имеется AI log

NelmioApiDocBundle поддерживает OpenAPI и может строить описание моделей с учетом Symfony Serializer и Validator; современные версии используют PHP attributes. [23]