Лабораторная работа 6: OpenAPI/Swagger контракт, роли и проксирование

Лабораторная работа 6: OpenAPI/Swagger контракт, роли и проксирование (основной артефакт исходный код для https://apps.thejeshgn.com/swagger-editor-next/ на основе подробного описания методов из лабораторнй работы 5, нужно продемонстрировать свагер и рассказать про каждый из методов, а также сами контракты. Альтернативная онлайн песочница https://devtoollab.com/tools/swagger-viewer щелкнуть "paste json/yaml")

Дисциплина: Проектирование архитектуры информационных систем
Продолжительность: 2 пары (3 акад. часа)
Форма проведения: работа с артефактами + защита
Основной артефакт: OpenAPI YAML/JSON (монолит) + матрица ролей + «три поверхности документации» (test/prod/admin) + контракт proxy-ручки

Цель

Сформировать навыки архитектурного контрактирования API через OpenAPI и управления доступами (аутентификация/авторизация/роли) как частью архитектуры безопасности. OpenAPI — стандарт описания HTTP API, пригодный для людей и инструментария. 

Исходные данные

Результаты предыдущей лабораторной (Postman и каталог эндпойнтов) + артефакты монолита (ЛР2).

Инструменты

Любой редактор текста + валидатор/просмотрщик OpenAPI (Swagger UI/Editor допустим). В части безопасности опираемся на модель Security Scheme / Security Requirement, которая описывается в OpenAPI. 

Структура работы

Часть A: Формализация API монолита в OpenAPI

1. Описать минимум 15 операций из ЛР «Postman» в формате OpenAPI 3.x.
2. Включить:

• info (название, версия),
• servers (минимум DEV и PROD),
• tags по модулям монолита,
• paths и components/schemas для основных моделей ответа/запроса.

OpenAPI позволяет описать API так, чтобы потребителю было достаточно спецификации для понимания возможностей. 

Часть B: Аутентификация и роли (RBAC) в контракте

1. Выбрать базовую схему: Bearer Token (JWT). JWT — стандартный формат передачи claims между сторонами. 
2. В OpenAPI описать security scheme для bearer auth и применить ее глобально или на отдельных операциях. Для bearer auth в OpenAPI задается type: http и scheme: bearer. 
3. Ввести минимум 3 роли (например USER, MANAGER, ADMIN) и составить матрицу доступа:

• какие операции доступны каждой роли,
• какие операции доступны без авторизации (например, health-check или публичный каталог).

Важно: на уровне безопасности API критичны корректные проверки авторизации на уровне объектов (типовой риск OWASP — broken object level authorization). 

Часть C: Три «поверхности» Swagger-документации (test / prod / admin)

Сделать один из вариантов (выберите один и обоснуйте):

Вариант 1 (рекомендуемый для учебной): три отдельных OpenAPI файла:

• openapi-test.yaml — включает тестовые/отладочные ручки (seed, mock, sandbox) и сервер DEV;
• openapi-prod.yaml — только продовый набор операций, сервер PROD;
• openapi-admin.yaml — админские ручки, отдельный базовый путь /admin/api, усиленная схема доступа (например, API key + bearer, или только bearer с ролью ADMIN).

Вариант 2: один файл, но с явным разделением:

• теги Public, User, Admin,
• разные servers,
• security requirements по операциям.

В отчете объяснить, зачем архитектор разделяет поверхности (минимизация атакующей поверхности, разные контуры эксплуатации, меньше риск «засветить» отладочные методы в проде).

Часть D: Proxy-ручка и «reverse proxy» в архитектуре монолита

1. Спроектировать минимум одну proxy-операцию внутри монолита — ручку, которая проксирует вызов во внешнюю систему (например, в платежный провайдер или внешнюю справочную систему).
2. В контракте обязателен раздел:

• входные параметры,
• какие заголовки/данные транслируются,
• таймаут/ретраи (описательно),
• как мапятся ответы и ошибки внешнего сервиса в ваши коды,
• ограничения по ролям.

Пояснить в 5–7 предложениях разницу:

• reverse proxy как инфраструктурный компонент перед приложением (маршрутизация/терминация TLS),
• proxy endpoint как прикладной контракт внутри монолита (интеграционный фасад).

Результаты

• OpenAPI спецификация(и): test/prod/admin.
• Матрица доступов «роль → эндпойнты».
• Описание proxy-ручки и маппинга ошибок.
• Короткий текст: почему выбран именно такой набор разделений.

Контрольные вопросы

• Зачем в архитектуре фиксировать API контракт в OpenAPI? 
• Чем Security Scheme отличается от Security Requirement в OpenAPI? 
• Как в OpenAPI описать Bearer Auth? 
• Почему «сломанная авторизация на уровне объектов» — один из самых опасных рисков API? 
• Что дает разделение Swagger на test/prod/admin в плане безопасности и управления изменениями?

Критерии оценивания

Корректность и полнота OpenAPI (30%), корректность security/ролей и матрицы доступа (25%), качество разделения поверхностей test/prod/admin (15%), архитектурная проработка proxy-ручки (20%), обоснования и связность с НФТ (10%).