Выпустил Swagger Parser 2.0. Два года я работал над ним параллельно с основной веткой 1.x, в которой продолжали выходить новые возможности и исправления.
Задача осталась прежней: взять схему API и сгенерировать Dart-модели и клиентов. В версии 2.0 появились новое ядро парсинга, больше вариантов генерации и веб-редактор. Часть возможностей v1 я убрал. Расскажу, что изменилось и как перейти на новую версию.
Отдельное ядро OpenAPI
Парсинг теперь находится в swagger_parser_core. Пакет читает JSON и YAML,
строит версионные модели документа, проверяет схему и разрешает ссылки.
Он поддерживает Swagger 2.0 и OpenAPI 3.0.x, 3.1.x и 3.2.x.
Модели основаны на спецификациях Swagger 2.0, OpenAPI 3.0.4, 3.1.2 и 3.2.1. Правила каждой версии остаются явными. Если нужно только прочитать или обработать схему, core можно использовать без генератора Dart-кода.
В проекте три библиотечных пакета:
swagger_parser_core: модели документа, парсинг, валидация и ссылки.swagger_parser: Dart-модели, HTTP-клиенты, конфигурация и CLI.swagger_parser_templates: отдельные Mustache-шаблоны и вспомогательные файлы.
Три HTTP-клиента и четыре сериализатора
HTTP-клиент можно выбирать независимо от сериализатора моделей.
| Настройка | Варианты | По умолчанию |
|---|---|---|
| HTTP-клиент | Retrofit + Dio, Dio, package:http | Retrofit + Dio |
| Сериализация | Обычные JSON-кодеки, json_serializable, Freezed, dart_mappable | Обычные JSON-кодеки |
У обычных моделей есть fromJson и toJson, которым не нужны пакеты
сериализации. С отдельным Dio или package:http не нужен и этап сборки клиента.
Для Retrofit и пакетных сериализаторов остаётся build_runner.
Методы поддерживают отмену запросов и настройки отдельных вызовов там, где это позволяет транспорт. Клиенты работают с формами, multipart-файлами и бинарными ответами. SSE сохранился. Для потоков записей добавлен JSON Lines, а для больших загрузок можно включить поток байтов.
По умолчанию тип результата метода выбирается по наименьшему точному коду 2xx
из схемы. Режим response_mode: all_statuses создаёт типизированные варианты
для описанных статусов. Их можно обрабатывать через Dart switch.
Модели учитывают поведение схемы
Генератор работает с $ref, allOf, oneOf и anyOf, в том числе с union-моделями
с дискриминатором и без него. Request- и Response-модели разделяются только
тогда, когда readOnly или writeOnly создаёт различия между ними.
Можно сохранять неизвестные значения enum и дискриминаторов, подключать свои
типы и кодеки, генерировать явные валидаторы DTO с путями полей.
summary и description по умолчанию переносятся в Dartdoc, а устаревшие
элементы получают аннотацию @Deprecated.
Для PATCH необязательные nullable-поля по умолчанию имеют тип T?, а null
не попадает в JSON. Если API различает отсутствие поля и явный JSON null,
можно включить use_presence_records.
Один публичный импорт
Клиенты группируются по первому тегу операции. Операции без тегов попадают в общий клиент. У каждого клиента своя папка, рядом — его модели. Общая модель относится к первому клиенту, который использует её по порядку операций в схеме.
Для схемы с тегом Stations структура может выглядеть так:
lib/generated/
api.dart
exports.dart
stations/
stations_client.dart
models/
station.dart
В api.dart находится класс Api и экспорт exports.dart. Одного импорта
достаточно для доступа к сгенерированным клиентам и моделям.
Через root_api_class_name можно переименовать основной класс и его файл.
Новый веб-редактор
Веб-редактор переписан на Dart и Jaspr. Можно вставить схему или загрузить JSON/YAML-файл, настроить конфиг через поля формы или YAML и скачать результат в ZIP-архиве. Структура папок сохраняется.
Для генератора, шаблонов и конфигурации есть отдельные вкладки.
Генерация выполняется локально в браузерном worker.
Pages поддерживает внутренние $ref; внешние ссылки доступны через CLI
и библиотечный API.
Свои шаблоны вынесены в отдельный пакет. Они могут дополнять или заменять
запланированные Dart-файлы и создавать вспомогательные классы, например Page<T>.
В основном пакете больше нет зависимости от Mustache. Шаблоны меняют исходный
код после разрешения схемы и сопоставления типов, но не сами эти этапы.
Начать можно с небольшого конфига
Версия 2.0 требует Dart 3.13 или новее в пределах ветки 3.x. Этот минимум нужен для совместимых версий пакетов генерации и сериализации, а также для использования primary constructors в DTO.
Добавьте генератор в проект:
dev_dependencies:
swagger_parser: ^2.0.0
Затем создайте swagger_parser.yaml:
swagger_parser:
schema_path: api/openapi.yaml
output_directory: lib/generated
generation:
http_client: dio
serializer: plain
Запустите:
dart pub get
dart run swagger_parser
В этом примере выбран отдельный Dio и обычные модели. Dio нужно добавить
в зависимости приложения; поддерживаемые версии пакетов есть в руководстве.
Для Retrofit укажите http_client: retrofit и выполните
dart run build_runner build. Если убрать generation, по умолчанию будут
выбраны Retrofit и обычные модели.
CLI сохраняет -f, -h и -o, а также загрузку схем по URL.
Команда validate проверяет схему, а --check сравнивает сгенерированные файлы
без записи. Для нескольких API есть inputs: у каждой схемы свои настройки
и папка результата. Настройки входа переопределяют общие поля, списки заменяются
целиком.
Что меняется при переходе с v1
Конфигурация изменилась. Вместо копирования старого конфига без правок используйте
справочник настроек. Новые ключи записываются в snake_case.
Из генератора удалены:
- Генерация Kotlin. Встроенный генератор теперь ориентирован на Dart.
- Генерация в один файл. Для доступа ко всему результату есть основной файл API.
- DTO без сериализации. Такой результат можно сделать через свои шаблоны.
Пользовательские шаблоны переехали в swagger_parser_templates с отдельным CLI.
Retrofit, Freezed, json_serializable, dart_mappable и SSE остались.
Начните переход с одной схемы. Проверьте diff генерации, настройте конфиг и импорты, при необходимости запустите builders и проверьте клиента с вашим API. В новой версии есть тесты на реальных JSON/YAML, проверки выходных файлов и тесты, которые собирают и запускают клиентов со всеми поддерживаемыми сериализаторами.
Можно попробовать веб-редактор, открыть описание релиза 2.0.0 или репозиторий.