typescript-openapi-generator

typescript-openapi-generator это пакет, который генерирует файлы с typescript определениями и файлы с хуками react-query из файлов спецификаций OpenAPI для работы с API в рамках платформы ENSI.

Для кого этот пакет нужен?

Для frontend разработчиков, работающих с ENSI.

Для чего этот пакет нужен?

• Сокращает время разработки: с помощью typescript-openapi-generator вам не нужно вручную писать хуки или обновлять типы для каждого API эндпоинта, определенной в спецификации OpenAPI. Он автоматически генерирует исходный код для вас, сокращая затраты на разработку.
• Обеспечивает согласованность API: typescript-openapi-generator гарантирует, что сгенерированные хуки и типы соответствуют спецификации OpenAPI, поскольку он напрямую полагается на спецификацию для генерации кода.
• Упрощает интеграцию API: обеспечивая плавную интеграцию вашего API с react-query, пакет упрощает процесс фетчинга, мутирования и кэширования ответов API, снижая сложность выборки данных и управления состоянием.

Как использовать?

1. Установите пакет с помощью npm

npm i -g @ensi-platform/typescript-openapi-generator

или yarn

yarn global add @ensi-platform/typescript-openapi-generator

2. Перейдите в существующий, или создайте проект admin-gui-frontend

3. Запустите команду:

yarn ts-openapi-gen init

В результате будет создан файл openapi-generator.json

Параметры, доступные для редактирования в файле openapi-generator.json:

Поле	Назначение	Пример
openapi_path	Полный URL до index.yaml с openapi-документацией	https://admin-gui-backend-master-dev.ensi.tech/api-docs/v1/index.yaml
output_path	Путь до папки, где будут сгенерированы файлы	./output/src/api
targets	Набор включенных плагинов. В данный момент доступно только ["react-query"]	["react-query"]
override_policies	Политика перезаписи. Словарь, где ключ - плагин, а значение одна из политик. В данный момент существуют политики: "override" - полная перезапись файла и "skip"- игнорирование существующих файлов	{"react-query": "skip","types": "override"}

Для react-query по ключу react-query можно так же изменить некоторые настройки:

Поле в объекте react-query	Назначение	Пример
imports	Массив дополнительных импортов в каждом файле с хуками	[{ "from": "@api/client", "name": "useAuthApiClient"}]
hooks	Массив дополнительных строк кода в теле каждого хука	["const apiClient = useAuthApiClient();"]
api_client_name	Название переменной экземпляра класса APIClient	apiClient
generate_invalidations	Включить эвристическое определение ключей поисковых запросов, подлежащих инвалидации	true

4. Сохраните файл конфигурации и напишите команду:

yarn ts-openapi-gen generate

Данная команда рекурсивно просканирует все референсы > ($ref) во всех определениях OpenAPI схемы. На основе схем входных и выходных данных в каждом эндпоинте создадутся определения интерфейсов, энамов и иных типов. Корректность выходных типов напрямую зависит от корректности openapi схем, поддерживаемых на стороне бэкенда. Если в targets включен react-query, то запускается генератор хуков, работающий по схожему с генератором типов принципу. После генераций, происходит эвристическая группировка файлов по папкам на основе общих префиксов и запись содержимого на диск.

Дождитесь окончания программы, и изучите содержимое папки, указанной в output_path.

Рекомендуется использовать типы как есть, и всегда выставлять в override_policies для types значение override. Однако хуки могут являться частью бизнес-логики, или требовать вспомогательных действий. Поэтому считайте, что фича с генерацией хуков предназначена для упрощения создания нового раздела, но не для полной автоматизации.