Лабораторная работа 7: Swagger Editor и генерация кода по OpenAPI (основной артефакт - скопировать исходный код для свагера из лабораторной 6 и вставить например сюда https://openapi-generator-ui.fugary.com/ нажать сгенерировать все, изучить и продемонстрировать содержимое архива, который сгенерируетс. Разобрать с ИИ сам код сгеренированный на java или другом любом языке, разобрать и рассказать что и как работает - разобрать сам проект полученный. Альтернативная онлайн песочница https://devtoollab.com/tools/swagger-viewer щелкнуть "paste json/yaml")
Дисциплина: Проектирование архитектуры информационных систем
Продолжительность: 2 пары (3 акад. часа)
Форма проведения: индивидуальная работа (генерация + архитектурное обоснование)
Основной артефакт: сгенерированный server stub и/или client SDK + обновленная компонентная архитектура монолита + мини-ADR
Цель
Показать практику «контракт → реализация»: на основе OpenAPI спецификации генерируется каркас серверной части или клиентский SDK. В индустрии это делается инструментами Swagger Codegen или OpenAPI Generator, которые умеют генерировать server stubs, SDK, документацию и конфигурацию из спецификации.
Исходные данные
OpenAPI спецификация монолита (из предыдущей лабораторной).
Инструменты
Swagger Editor/Swagger UI допустимы для просмотра/валидации; генерация кода может выполняться OpenAPI Generator или Swagger Codegen.
Структура работы
Часть A: Валидация и «причесывание» контракта
- Проверить OpenAPI файл на корректность (ошибки схем, отсутствующие $ref, неконсистентность моделей).
- Доработать контракт: унифицировать ответы ошибок (единый ErrorResponse), привести названия схем и полей к единому стилю, добавить примеры.
Часть B: Генерация server stub для монолита
- Сгенерировать server stub в одном выбранном стеке (любой из реально поддерживаемых генератором).
- В отчете приложить:
- дерево каталогов сгенерированного проекта,
- перечень контроллеров/ручек,
- список моделей (DTO), которые появились из
schemas.
OpenAPI Generator прямо заявляет поддержку генерации и клиентов, и серверных заготовок по OpenAPI 2.0/3.x.
Часть C: Генерация client SDK (минимально)
Сгенерировать клиентский SDK (можно в другом языке, чем сервер), приложить:
- как выглядит вызов одной операции,
- какие модели используются.
Часть D: Архитектурная интеграция в монолит (важный смысловой блок)
Поскольку мы в курсе «архитектура», а не «кодинг», студент делает архитектурное описание:
- Как вы встроите сгенерированные контроллеры в слоистую архитектуру монолита (из ЛР2):
- где граница API слоя,
- как контроллер вызывает Application/Domain слой,
- какие части нельзя «засовывать» в контроллеры (бизнес-правила должны быть в домене).
- Обязательный мини‑ADR (1 шт.) по шаблону:
- Контекст: хотим контрактный подход.
- Решение: design-first + генерация каркаса.
- Последствия: плюсы/минусы (ускорение, единообразие vs риск перегенерации, необходимость дисциплины).
Результаты
- Папка со сгенерированным server stub.
- Папка со сгенерированным client SDK.
- Обновленная диаграмма компонентов монолита (появляется «Generated API Layer»).
- Мини‑ADR.
Контрольные вопросы
- Почему OpenAPI подходит для генерации кода и что именно генерируется?
- В чем риск «перегенерации» и как архитектор предлагает его снижать (слои, частичные классы, шаблоны)?
- Чем design-first отличается от code-first, и когда что целесообразнее?
Критерии оценивания
Факт корректной генерации и полнота артефактов (25%), качество архитектурного встраивания (35%), корректность слоев и границ ответственности (20%), ADR и аргументация (20%).