Swagger/OpenAPI генерация для TypeScript

Swagger/OpenAPI генерация для TypeScript: Полное руководство по инструментам

Разработка современных веб-приложений на TypeScript неразрывно связана с созданием типобезопасных API-клиентов. Ручное написание интерфейсов для каждого эндпоинта — трудоёмкая и подверженная ошибкам задача. К счастью, существует мощный подход — автоматическая генерация TypeScript-кода из OpenAPI (Swagger) спецификаций. В этой статье мы подробно разберём лучшие инструменты для этой задачи, их возможности и примеры использования.

Почему стоит использовать генерацию из OpenAPI?

OpenAPI (ранее Swagger) — это стандарт описания REST API. Используя YAML или JSON файл спецификации, вы получаете:

Типизацию на 100% — TypeScript интерфейсы, точно соответствующие схеме запросов и ответов
Синхронизацию с бэкендом — при изменении API достаточно перегенерировать код
Снижение ошибок — компилятор TypeScript отлавливает несоответствия типов на этапе разработки
Автодополнение в IDE — IntelliSense подсказывает поля и типы

Топ инструментов для генерации TypeScript из OpenAPI

1. openapi-typescript-codegen (рекомендуемый)

Этот инструмент завоевал популярность благодаря простоте и современному подходу. Он генерирует чистый, хорошо структурированный код с поддержкой axios или fetch.

Установка:

npm install -D openapi-typescript-codegen

Пример использования:

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

Генерируемый код:

// generated/models/User.ts
export interface User {
    id: number;
    name: string;
    email: string;
    role: 'admin' | 'user';
}

// generated/services/UserService.ts
export class UserService {
    public async getUsers(): Promise<User[]> {
        return this.httpRequest.request({
            method: 'GET',
            url: '/users',
        });
    }
}

Преимущества:

Поддержка OpenAPI 3.0 и 3.1
Генерация моделей, сервисов и типов для запросов
Опциональная генерация хуков для React Query
Настраиваемые шаблоны через Handlebars

2. OpenAPI Generator (openapi-generator)

Официальный генератор от сообщества OpenAPI. Поддерживает более 50 языков, включая TypeScript (несколько генераторов).

Установка:

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

Пример использования:

npx openapi-generator-cli generate \
    -i spec.yaml \
    -g typescript-axios \
    -o ./generated

Генерируемый код:

// generated/api.ts
export const UsersApiAxiosParamCreator = {
    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {
        const localVarPath = `/users`;
        return {
            url: localVarPath,
            method: 'GET',
        };
    }
}

Особенности:

Генераторы: typescript-axios, typescript-fetch, typescript-angular
Поддержка авторизации (OAuth2, API Key)
Генерация документации и тестов
Работа через CLI или Maven/Gradle плагины

3. swagger-typescript-api

Лёгкий и быстрый генератор, ориентированный на чистый TypeScript без лишних зависимостей.

Установка:

npm install -D swagger-typescript-api

Пример использования:

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

Генерируемый код:

// generated/api.ts
export type GetUsersResponse = {
    data: User[];
    total: number;
};

export class Api<SecurityDataType> {
    public getUsers = (): Promise<GetUsersResponse> => {
        return this.request<GetUsersResponse>({
            method: 'GET',
            url: '/users',
        });
    }
}

Преимущества: