Приветствую,

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

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

Одной из технологий, которая хорошо зарекомендовала себя для таких задач, является автоматическая генерация кода из OpenAPI-спецификаций.

Проблема контрактов: Почему договорённости «на словах» — это всегда боль?

На ранних этапах разработки небольших приложений команды фронтенда и бэкенда часто общаются в духе: «Ну, давайте договоримся по-человечески! JSON будет выглядеть вот так, ок?» — «Ок». Звучит красиво, как обещание встретиться через 5 лет на том же самом месте

Через месяц — фронтенд уже привязан к старому контракту, бэкенд решил "немножко улучшить", но оспорить договорённости уже никто не может, потому что они, конечно же... устные. Возникает классическая ситуация:

Бэкенд: «Ну вы же знаете, как у нас на REST принято, мы заменили userId на clientUuid и вынесли персональные данные в отдельную модель, всё же логично».
Фронтенд: звуки паники и негодования
QA: «Бэк прекрасно работает, я завел 100500 багов на команду фронта»
Менеджер: «У меня показ через два часа, вам что, трудно просто починить?»

Именно в такие моменты ты понимаешь: лучше потратить пару часов на генерацию контрактов, чем бесконечно «синхронизироваться» с другим разработчиком в Slack.

Вот основные проблемы, с которыми сталкиваются команды:

Разрозненные форматы запросов и ответов. API постоянно дополняется, а разрыв между фронтом и бэком увеличивается.
Непредсказуемые изменения. Бэкендеры добавляют функционал, ломает фронт — часто случайно.
Отсутствие актуальной документации. Никто не сообщает вовремя, если изменилось поведение эндпоинта.
Ручная валидация. Отправка запросов руками, разбор ошибок — всё это тратит гигантский объём времени.

Главная идея: автоматизация вместо рутины

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

Почему это нужно?

Точность данных: автоматическая генерация интерфейсов устраняет вероятность ошибки в типах.
Скорость разработки: вместо создания моделей вручную, разработчики получают готовый код, который можно использовать сразу.
Простота обновлений: если изменяется контракт на бэкенде, достаточно обновить OpenAPI-описание и снова сгенерировать файлы — для фронтенда всё обновится автоматически.
Снижение нагрузки на разработчиков: команды могут сосредоточиться на функциональной логике, вместо того чтобы тратить время на синхронизацию данных.

Как внедрять в проекты?

1. Интеграция и генерация документации Swagger

На первом этапе ключевая задача - сделать API «говорящим». Это важно как для фронта (нет времени залезать в бэк-код, чтобы понять, как отправить запрос), так и для тестировщиков.

Мы установили автоматическую генерацию документации, которая поднимается на Swagger UI по адресу /api-docs.

На C# подключение сводится к установке библиотеки Swashbuckle.AspNetCore && Swashbuckle.AspNetCore.Annotations и нескольким строкам кода в Program.cs(Startup.cs)

services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "Api", Version = "v1" });
            var currentAssembly = Assembly.GetExecutingAssembly();
            var xmlDocs = currentAssembly.GetReferencedAssemblies()
                .Union(new[] { currentAssembly.GetName() })
                .Select(a => Path.Combine(Path.GetDirectoryName(currentAssembly.Location), $"{a.Name}.xml"))
                .Where(f => File.Exists(f)).ToArray();
            xmlDocs.ToList().ForEach(d =>
            {
                c.IncludeXmlComments(d);
            });
        });
        ...
        
app.UseSwagger();
app.UseSwaggerUI();

Для других языков подключение Swagger'a не представляет никакой проблемы - огромное количество примеров в сети под любой кейс позволят быстро развернуть его практически под любой стэк

Основные преимущества Swagger:

Удобный визуальный интерфейс для просмотра эндпоинтов.
Лёгкость встраивания в CI/CD для генерации актуальной документации.
Возможность предоставить всем участникам команды (фронт, тестировщики, аналитики) простой доступ к текущему состоянию API.

2. Генерация моделей фронтенда с помощью ng-openapi-gen

Учитывая то, что основа фронта у нас Angular, для генерации моделей и сервисов на основе OpenAPI-схем была выбрана библиотека ng-openapi-gen. Этот инструмент в полуавтоматическом режиме создаёт Angular-сервисы и модели из OpenAPI-спецификации, избавляя разработчиков от необходимости вручную описывать структуры данных и запросы.

Подготовка OpenAPI-спецификации

Для управления процессом генерации создается файл json (в произвольном месте), свой под каждый источник данных (приложение может работать с множеством различных API):

{
  "$schema": "../../../../node_modules/ng-openapi-gen/ng-openapi-gen-schema.json",
  "input": "https://localhost:5001/swagger/docs/v1/backend-name", // адрес доков бэка
  "output": "src/app/api/backend-name", // место развертывания генерируемых моделей
  "ignoreUnusedModels": false,
  "indexFile": true,
  "removeStaleFiles": true,
  "skipJsonSuffix": true,
  "module": "ApiModule",
  "configuration": "ApiConfiguration"
}

Генерация кода

В package.json добавляем новый скрипт:

"openapi-gen-backend-name": "ng-openapi-gen -c <путь к файлу из предыдущего шага>/config.json"

Вот и все, для генерации сервисов и моделей достаточно выполнить:

npm run openapi-gen-backend-name

После выполнения команды, в указанной директории (в нашем случае, src/app/api/backend-name) появятся автоматически сгенерированные модели, сервисы и ApiModule, который можно подключить в вашем приложении.

...

@NgModule({
  imports: [
    ...
    ApiModule.forRoot({rootUrl: 'https://localhost:5001'})
  ]
})
export class AppModule {}

Использование моделей и сервисов

Сгенерированные модели и сервисы предоставляют строгую типизацию и удобный интерфейс для API-запросов. Например, модель User и сервис UserService, которые генерируются автоматически:

Пример сгенерированных моделей:

export interface User {
  id: number;
  name: string;
}

Пример сгенерированного сервиса:

...

@Injectable({
  providedIn: 'root'
})
export class UserService {
  constructor(private http: HttpClient) {
  }

  getUsers(): Observable<User[]> {
    return this.http.get<User[]>('/users');
  }
}

Теперь сервис можно использовать в любом компоненте вашего Angular-приложения:

Зачастую код созданных сервисов выглядит странновато и не особо удобен для чтения, но смысл в том, что нам и не надо его особо читать, нас интересует только контракт

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

...

@Component({
  selector: 'app-user-list',
  template: `
    <div *ngFor="let user of users">
        {{ user.name }} (ID: {{ user.id }})
    </div>
  `
})
export class UserListComponent implements OnInit {
  users: User[] = [];

  constructor(private userService: UserService) {
  ngOnInit(): void {
    this.userService.getUsers().subscribe((data) => {
      this.users = data;
    });
  }
}

Альтернативы

Стоит отметить, что использование OpenAPI не ограничивается только Angular или фронтенд-разработкой. Описанные подходы масштабируются на множество популярных технологий. Например, для React и TypeScript широко применяются библиотеки вроде openapi-typescript-codegen и swagger-typescript-api, которые позволяют сгенерировать строго типизированные клиенты для API. В экосистемах Python и Java инструменты вроде openapi-generator помогают сократить время на разработку серверных и клиентских приложений, генерируя код под задачи, от Flask и Django до Spring Boot и Kotlin.

Это доказывает, что основное преимущество OpenAPI — универсальность. Независимо от языков или фреймворков, OpenAPI позволяет объединить команды фронтенда, бэкенда и QA вокруг единого контракта, минимизируя человеческий фактор и ошибки интеграции. Независимо от того, работает ли ваша команда с веб-технологиями, мобильными платформами или серверными приложениями, OpenAPI и инструменты автоматической генерации помогут стандартизировать процесс и ускорить разработку.

Инструмент	Языки/Фреймворки	Особенности
`openapi-typescript-codegen`	React, TypeScript	Компактный генератор клиентов с типами.
`openapi-generator`	Vue, Svelte, Python, Java, Kotlin и др.	Мощный, мультиплатформенный инструмент.
`swagger-typescript-api`	React, Node.js, TypeScript	Лёгкий и быстрый генератор с CLI.

Рекомендации по выбору инструмента

Если используете Angular, ваш лучший друг — это ng-openapi-gen.
Для React/TypeScript выберите openapi-typescript-codegen или swagger-typescript-api. Обе библиотеки подходят для разных сценариев.
Для сложных или многоязычных проектов используйте openapi-generator, так как он поддерживает более широкий набор платформ и языков.
Работаете с фреймворками вроде Django или Spring? openapi-generator может генерировать даже серверный код.

3. Интеграция OpenAPI в CI/CD

Особое внимание стоит уделить автоматизации проверки контрактов на уровне pipelines, чтобы избежать рассинхронизации между фронтом и бэком.

Что полезно добавить в CI/CD:

Автогенерацию документации (Swagger на стороне бэка) для каждого деплоя.
Проверку спецификации с помощью инструментов вроде swagger-cli или openapi-cli.
Синхронизацию моделей фронтенда на этапе сборки (проверок высокого полёта тут, imho, не получится, но сам факт инвалидации кода и, как следствие невозможность компиляции, в случае неучтенного изменения сигнатур бэка уже помогает существенно сократить время реакции).

Результаты: что дало внедрение OpenAPI?

После нескольких месяцев активного использования мы заметили следующие улучшения:

Снижение количества ошибок: Благодаря строгой типизации проблемы обнаруживаются ещё до выполнения запросов.
Скорость разработки: Автоматизация генерации моделей и документации сократила время на обновление API и его интеграцию.
Прозрачность: Swagger UI и сгенерированные типы упростили понимание структуры API для новичков в команде.
Стабильное взаимодействие: QA-команды получили доступ к документации через Swagger, а фронтендеры начали работать с читабельными интерфейсами.

Заключение

Наладить взаимодействие между фронтендом и бэкендом — задача не из лёгких, особенно когда ваш проект растёт, а контрактов становится всё больше. Автоматическая генерация моделей и сервисов для фронтенда помогает избавиться от рутины, снизить риски рассинхронов и ускорить разработку. Вместо ручного написания интерфейсов или работы с неподтверждёнными контрактами вы получаете единый источник истины, который синхронизируется буквально за пару команд.

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

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

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

Как победить хаос ручных контрактов с бэкендом: автоматизация моделей в Angular