Авто-генерация типизированных API контроллеров на клиенте из Swagger

Привет! Меня зовут Данил, я Frontend разработчик, живу в Питере, работаю в компании Unistory. Решил рассказать на Хабре, как автоматизировать один нудный процесс.

Проблематика

Зачастую нам приходится описывать запросы или переписывать уже имеющиеся ввиду изменения каких-то DTO (Data Transfer Object) или параметров у запросов. Это вполне естественно для разработки, но часто оказывается скучным и однотипным процессом, не требующим размышлений или особых навыков. Как следствие, его автоматизация кажется отличным выходом.

Решение

Автоматизация генерации API-контроллеров на клиенте возможна с помощью инструментов openapi-merge-cli и swagger-typescript-api. Они позволяют генерировать код на основе OpenAPI (Swagger) спецификации, минимизируя ручной труд и снижая вероятность ошибок.

Когда это уместно?

Данное решение отлично подходит для быстрого старта в проектах уровня MVP (Minimum Viable Product) или PoC (Proof of Concept). Однако, при разработке масштабируемого продукта с гибкой архитектурой оно может накладывать определенные ограничения, и в таких случаях стоит рассмотреть более детальную кастомизацию API-клиента.

Начало работы

Установка зависимостей:

npm i --save-dev openapi-merge-cli swagger-typescript-api

Добавление скриптов:

"merge-openapi": "npx openapi-merge-cli --config ./swagger/openapi.config.json", "codegen:api": "node codegen/codegen.js", "codegen": "npm run merge-openapi && npm run codegen:api",

Структура проекта:

 project-root  ├──  api                    # Папка для сгенерированных файлов (создается вручную пустой!)  │    ├── Users.ts             # Контроллер для работы с пользователями  │    ├── Orders.ts            # Контроллер для работы с заказами  │    ├── http-client.ts       # HTTP-клиент (обертка над axios/fetch)  │    ├── data-contracts.ts    # Типы и DTO, сгенерированные из спецификации  │    ├── openapi.json         # Объединённая OpenAPI спецификация после merge  │  ├──  codegen                # Папка с кодогенерацией API-клиента  │    ├── codegen.js           # Скрипт генерации API-клиента на основе OpenAPI спецификации  │  ├──  swagger                # Папка с OpenAPI спецификациями  │    ├── openapi.config.json  # Конфигурация объединения OpenAPI схем  │    ├── api.swagger.json     # OpenAPI спецификация бэкенд-сервиса (может быть несколько)  │    ├── users.swagger.json   # Спецификация для сервиса пользователей (если API разбито на части)  │    ├── orders.swagger.json  # Спецификация для сервиса заказов (если API разбито на части)  │  ├──  src                    # Папка с кодом проекта  │  ├── package.json              # Конфигурация проекта, включая npm-скрипты для генерации API

Разберем подробнее пакеты и скрипты

openapi-merge-cli

Что делает?

openapi-merge-cli объединяет несколько OpenAPI-спецификаций в один файл.

Зачем?

Если у тебя API разбито на несколько частей (**-**например, users.json, orders.json), этот шаг создает единый openapi.json, который потом передаётся в генератор.

Как это работает в коде?

Чтобы объединить несколько OpenAPI-файлов в один, используется конфигурационный файл swagger/openapi.config.json. Он указывает, какие файлы должны быть объединены и куда сохранить итоговый результат.

Пример openapi.config.json:

// /swagger/openapi.config.json  {   "inputs": [     {       "inputFile": "./users.swagger.json"     },     {       "inputFile": "./orders.swagger.json"     }   ],   "output": "../api/openapi.json" }

Разбор конфигурации:

• inputs – массив с путями к OpenAPI-файлам, которые нужно объединить. В этом примере соединяются users.swagger.json и orders.swagger.json.

• output – путь, куда будет сохранён объединённый файл openapi.json.

swagger-typescript-api

Что делает?

swagger-typescript-api — это инструмент для генерации API-клиента и типов на основе OpenAPI-спецификации. Он анализирует openapi.json и создаёт готовый TypeScript-код для работы с API.

Основные возможности:

• Генерация полностью типизированных API-запросов.

• Автоматическое создание моделей (DTO) на основе OpenAPI-спеки.

• Поддержка разных подходов: fetch, axios и других.

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

Зачем?

• Упрощает работу с API — тебе не нужно вручную писать интерфейсы и запросы.

• Снижает вероятность ошибок, так как весь API-клиент типизирован.

• Позволяет легко поддерживать актуальность API-кода при изменении бэкенда.

Как это работает в коде?

Файл codegen/codegen.js (который вызывается командой npm run codegen:api) нужно создать вручную, если его нет в проекте. В этом файле содержится конфигурация для кодгена swagger-typescript-api

// /codegen/codegen.js  import path from 'path' import { generateApi } from 'swagger-typescript-api'  // Генерация API-клиента на основе OpenAPI-спецификации generateApi({   // Имя выходного файла (если modular: false)   name: 'api.ts',    // Использовать единый HTTP-клиент (axios)   singleHttpClient: true,    // Выбор HTTP-клиента (axios или fetch)   httpClientType: 'axios',    // Разбить API-клиент на модули (файлы)   modular: true,    // Выносить тело запроса в отдельный параметр   extractRequestBody: true,    // Выносить query и path параметры в отдельный параметр   extractRequestParams: true,    // Выносить тело ответа в отдельный параметр   extractResponseBody: true,    // Выносить ошибки API в отдельный параметр   extractResponseError: true,    // Генерировать типы ответов API   generateResponses: true,    // Использовать объединённые enum-типы (`enum | string`)   generateUnionEnums: true,    // Исправлять ошибки OpenAPI-спеки (если есть несовместимости)   patch: true,    // Генерировать клиент для работы с API   generateClient: true,    // Индекс для именования модулей API   moduleNameIndex: 1,    // Путь к OpenAPI-файлу   input: path.resolve(process.cwd(), './api/openapi.json'),    // Папка для сохранения сгенерированного кода   output: path.resolve(process.cwd(), './api'), })

Этот скрипт выполняет генерацию API-клиента на основе OpenAPI-спецификации. Он берет openapi.json, создаёт типизированные запросы и модели данных, а затем сохраняет их в ./api.

Общий процесс генерации API

1. Получаем API спецификацию → На странице сваггера находим OpenAPI JSON-схему. Как правило, она находится под названием проекта.

   

   Если схемы нет, бекендер должен её описать в коде, используя инструменты типа NestJS Swagger, FastAPI, SpringDoc или другие подходящие для его стека. Без этого генерация API-клиента невозможна.

   Также в данной реализации важно понимать, что при обновлениях бекенда, необходимо каждый раз обновлять спеку на клиенте и выполнять команду npm run codegen, но если статья вам покажется интересной, я обязательно напишу продолжение, в котором реализую автоматическое подтягивание спеки.

2. Выгружаем JSON схему на клиент → Полученную спеку нужно сохранить в файл swagger/api.swagger.json , если таковых несколько, разбиваем их по отдельным файлам и указываем пути в swagger/openapi.config.json , как правило схема отражает сервис с которым вы работаете.

Пример с одним бекенд сервисом:

// /swagger/openapi.config.json  {   "inputs": [     {       "inputFile": "./api.swagger.json"     }   ],   "output": "../api/openapi.json" }

Пример с отдельными сервисами:

// /swagger/openapi.config.json  {   "inputs": [     {       "inputFile": "./identity.swagger.json"     },      {       "inputFile": "./payment.swagger.json"     },     {       "inputFile": "./users.swagger.json"     },     {       "inputFile": "./admin.swagger.json"     }   ],   "output": "../api/openapi.json" }

3. Запускаем скрипт слияния и генерации → Для удобства я создал скрипт, который объединяет две команды в одну: npm run codegen. В результате выполнения мы получаем папку api в корне проекта с автоматически сгенерированными типами и контроллерами для работы с API. Внутри папки будут следующие файлы:

   • http-client.ts — сгенерированный HTTP-клиент, обёртка над axios, содержащая базовую логику запросов, работу с заголовками, авторизацией и обработку параметров.

   • data-contracts.ts — автоматически сгенерированные TypeScript-типы, соответствующие моделям из OpenAPI. Используются для типизации данных в проекте.

   • openapi.json — объединённый файл спецификации OpenAPI, описывающий все доступные API-эндпоинты.

   • Auth.ts, Users.ts и другие контроллеры — автоматически сгенерированные файлы с методами для работы с API. Они формируются на основе эндпоинтов, описанных в Swagger (OpenAPI), и содержат готовые функции для выполнения запросов. Например, Auth.ts включает методы для авторизации (login, logout), а Users.ts — для работы с пользователями (getUser, updateUser).

     Чтобы использовать контроллеры, необходимо создать экземпляр HttpClient и передать его в контроллеры, обеспечивая единую точку конфигурации для запросов в проекте.

4. Объявляем HTTP Client → Создаем экземпляр HttpClient из сгенерированного кода, указывая базовый URL и необходимые параметры — фактически это аналог инстанса axios для работы с API. Файл с клиентом (http-client.ts) может располагаться в разных местах в зависимости от архитектурной методологии проекта (например, в папке services, lib или api). В моем случае это FSD (Feature-Sliced Design), где такой файл обычно находится в папке shared/api или shared/lib

   // /src/shared/api/http-client.ts  import { HttpClient } from '@api/http-client' import { Constants } from '@shared/lib'  export const httpClient = new HttpClient({   baseURL: Constants.API_URL,   // Другие параметры по необходимости }) 

5. Объявляем API-контроллеры → Создаём экземпляры сгенерированных контроллеров. В зависимости от архитектурного подхода их можно инициализировать прямо в http-client.ts для простого варианта или разделить код на модули, объявляя контроллеры внутри соответствующих модулей. Такой подход позволяет лучше структурировать код и упрощает масштабирование проекта.

   • Пример базовый:

     // /src/shared/api/http-client.ts  import { Auth } from '@api/Auth' import { Invoices } from '@api/Invoices' import { OAuthAccount } from '@api/OAuthAccount' import { Payments } from '@api/Payments' import { Subscriptions } from '@api/Subscriptions' import { Users } from '@api/Users' import { UserSubscriptions } from '@api/UserSubscriptions'  import { HttpClient } from '@api/http-client' import { Constants } from '@shared/lib'  export const httpClient = new HttpClient({   baseURL: Constants.API_URL,   // Другие параметры по необходимости })  // Auth controllers export const authController = new Auth(httpClient) export const authIntegrationsController = new OAuthAccount(httpClient)  // Subscriptions controllers export const invoicesController = new Invoices(httpClient) export const paymentsController = new Payments(httpClient) export const subscriptionsController = new Subscriptions(httpClient) export const userSubscriptionsController = new UserSubscriptions(httpClient)  // Users controllers export const usersController = new Users(httpClient) 

   • Пример с сущностями / модулями:

     // /src/entites/user/api/users-controller.ts  import { httpClient } from '@shared/api' import { Users } from '@api/Users'  export const usersController = new Users(httpClient) 

     // /src/entites/auth/api/auth-controller.ts  import { httpClient } from '@shared/api' import { OAuthAccount } from '@api/OAuthAccount' import { Auth } from '@api/Auth'  export const authController = new Auth(httpClient) export const authIntegrationsController = new OAuthAccount(httpClient) 

Что мы имеем?

Представим, что наш сваггер выглядел так:

После всех вышеперечисленных действий в папке api мы получим такую структуру:

 project-root  ├──  api                     # Папка для сгенерированных файлов (создается вручную пустой!)  │    ├── Admins.ts             # Контроллер для работы с администраторами  │    ├── Auth.ts               # Контроллер для работы с аутентификацией  │    ├── CounterNftLotOffers.ts # Контроллер для управления ставками на NFT-лоты  │    ├── Lots.ts               # Контроллер для работы с лотами  │    ├── Nft.ts                # Контроллер для работы с NFT  │    ├── NftLots.ts            # Контроллер для работы с коллекциями NFT  │    ├── Notifications.ts      # Контроллер для работы с уведомлениями  │    ├── PrivateOrders.ts      # Контроллер для частных заказов  │    ├── ScDeals.ts            # Контроллер для сделок  │    ├── ScDealsCharts.ts      # Контроллер для графиков по сделкам  │    ├── SeasonRewardHistories.ts # Контроллер для истории сезонных наград  │    ├── SeasonUsers.ts        # Контроллер для сезонных пользователей  │    ├── Seasons.ts            # Контроллер для сезонов  │    ├── Users.ts              # Контроллер для пользователей  │    ├── http-client.ts        # HTTP-клиент (обертка над fetch/axios)  │    ├── data-contracts.ts     # Типы и DTO, сгенерированные из OpenAPI спецификации  │    ├── openapi.json          # Объединённая OpenAPI спецификация после merge  │  ├──  codegen                 # Папка с кодогенерацией API-клиента  │    ├── codegen.ts            # Скрипт генерации API-клиента на основе OpenAPI спецификации  │  ├──  swagger                 # Папка с OpenAPI спецификациями  │    ├── openapi.config.json   # Конфигурация объединения OpenAPI схем  │    ├── nft-market.swagger.json # OpenAPI спецификация NFT-маркета  │  ├──  src                     # Папка с кодом проекта  │  ├── package.json               # Конфигурация проекта, включая npm-скрипты для генерации API  ├── tsconfig.json              # Конфигурация TypeScript (если используется TS)  

Описание файлов:

1. Admins.ts, Auth.ts, CounterNftLotOffers.ts, …, Users.ts

   • Каждый файл представляет API-контроллер для соответствующей сущности.

   • Содержит классы и методы для запросов (GET, POST, PUT, DELETE).

   • Использует HTTP-клиент для выполнения запросов.

2. data-contracts.ts

   • Описывает типы данных (интерфейсы) для запросов и ответов API.

   • Используется во всех контроллерах.

3. http-client.ts

   • Отвечает за отправку HTTP-запросов.

   • Может содержать кастомную логику для работы с токенами и авторизацией.

4. openapi.json

   • Исходный OpenAPI (Swagger) JSON, на основе которого была сгенерирована API-структура.

Важно!

Не изменяйте вручную файлы контроллеров и типов — после обновления API и повторной кодогенерации ваши правки будут перезаписаны.

Если необходимо изменить типы, делайте это на уровне вашего приложения, расширяя или объединяя их, вместо редактирования сгенерированных файлов.

Как работать с полученными контроллерами и типами?

Если вы выполнили все описанные выше шаги, у вас уже есть готовые экземпляры API-контроллеров.

// /src/shared/api/http-client.ts  import { Auth } from '@api/Auth'  import { HttpClient } from '@api/http-client' import { Constants } from '@shared/lib'  export const httpClient = new HttpClient({   baseURL: Constants.API_URL,   // Другие параметры по необходимости })  // Auth controllers export const authController = new Auth(httpClient) 

Дальнейшее взаимодействие зависит от вашего подхода к работе с запросами и используемого фреймворка или библиотеки. В React это может быть react-query, rtk-query и другие. В следующей статье я подробнее разберу, как интегрировать кодген с кешированием через react-query.

Посмотрим на практический пример работы с сгенерированными контроллерами.

Видео версия:

Если вы не хотите импортировать типы и контроллеры из внешней папки, вы можете объявлять типы на уровне сущности или модуля, используя реэкспорт или расширение/объединение типов.

---

Вот так я автоматизирую генерацию API-контроллеров на проектах Unistory. Планирую и дальше публиковать на Хабре такие гайды. Надеюсь, эта статья была полезной