OpenAPI Generator: как установить и настроить

В данной статье рассказано как установить и настроить OpenAPI Generator под Windows 10/11. Данная инструкция подойдёт и для серверных версий Windows Server 2012 R2/2016/2019/2022. Для этих целей удобно использовать виртуальную машину, которую можно заказать на сайте ruvds.com.

Общие сведения об OpenAPI Generator

OpenAPI Generator — это инструмент, который позволяет автоматически генерировать клиентские библиотеки, серверные скелеты, документацию и другие артефакты на основе спецификации OpenAPI. OpenAPI (ранее известный как Swagger) — это стандартный формат описания RESTful API, который позволяет описывать конечные точки, методы, параметры, модели данных и другую информацию в формате JSON или YAML.

Основные возможности OpenAPI Generator включают:

• Генерация клиентских библиотек: Возможно создавать клиентские библиотеки на различных языках программирования (таких как Java, Python, TypeScript, C#, Ruby и др.), которые позволяют взаимодействовать с RESTful API, описанным в спецификации OpenAPI.

• Генерация серверных скелетов: Инструмент может генерировать начальные серверные реализации (скелеты) для различных языков программирования и фреймворков. Это позволяет разработчикам быстро начать разработку серверной части, реализуя только бизнес-логику.

• Генерация документации: Есть возможность генерировать статическую документацию (HTML, Markdown и др.) для API, что облегчает понимание и использование API как для разработчиков, так и для пользователей.

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

Установка OpenAPI Generator под Windows

Сначала необходимо установить NodeJS с npm. Переходим на сайт https://nodejs.org/ и скачиваем последнюю LTS версию. Установщик NodeJS по умолчанию предлагает добавить пути до исполняемых файлов в переменную PATH. Рекомендуем оставить эту опцию выбранной для удобства работы.

Открываем Powershell и проверяем версии node и npm.

node --version

npm --version

Для правильной работы OpenAPI Generators необходим Java свежей версии. Поэтому нам необходимо скачать и установить Java JDK для Windows по адресу https://www.oracle.com/java/technologies/downloads/. Скачиваем и устанавливаем JDK 22 или новее.

Открываем Powershell (если у вас уже открыто окно Powershell, то нужно его закрыть и открыть снова), и проверяем, что java установлен:

java --version

Теперь мы готовый установить OpenAPI Generators. Его можно установить как глобально для NodeJS, так и локально для данного проекта. Мы установим глобально. Для локальной установки нужно убрать флаг -g.

npm install -g @openapitools/openapi-generator-cli

Проверяем версию:

npx @openapitools/openapi-generator-cli version

Генерация клиента из разметки OpenAPI

Заходим на сайт с документаций API RUVDS: https://ruvds.com/api-docs/ и скачиваем файл ruvds-api-v2.yaml

На странице со списком клиентов https://openapi-generator.tech/docs/generators, выбираем ваш любимый язык программирования и запускаем соответствующую команду. Мы выбрали powershell.

npx @openapitools/openapi-generator-cli generate -i ruvds-api-v2.yaml -g powershell

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