Типизация REST API для фронтенд разработчика

в 15:14, , рубрики: javascript, nswag, ReactJS, TypeScript

Сегодня широкое распространение имеют следующие подходы для описания взаимодействия браузера и сервера, такие как OpenApi & GraphQL.

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

Типизация REST API для фронтенд разработчика - 1

Эти инструменты помогают нам:

  • Разрабатывать и моделировать API в соответствии со стандартами на основе спецификаций
  • Создавать стабильный, многократно используемый код для вашего API практически на любом языке
  • Улучшить опыт разработчика с помощью интерактивной документации API
  • Легко проводить функциональные тесты на ваших API
  • Создавать и применять лучшие рекомендации по стилю API в вашей API архитектуре

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

Фронтенд приложение не скомпилируется если команда допустила ошибку в типах данных, которые принимает/поставляет REST API.

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

Для того чтобы получить все вышеописанные преимущества статически типизированного API нам необходимо воспользоваться генератором кода, который по OpenAPI спецификации сможет сгенерировать файлы с описанием типов, для Typescript это *.d.ts файлы.

В нашем проекте используется микросервисная архитектура и весь бекенд написан на .NET поэтому для генерации клиентов API для фронтенда/бэкенда мы использовали NSwag. Этот инструмент позволяет генерировать OpenAPI документы, которые затем в свою очередь уже используются для генерации кода клиентов.

Архитектура

В общем случае процесс генерации кода состоит из нескольких этапов:

  • Генерация OpenAPI документа
  • Генерация кода по OpenAPI документу

В нашем случае бекенд написан с использованием .Net и основной язык разработки C# этим обусловлен выбор инструментов. Мы для генерации OpenAPI документов и клиентов используем один и тот же инструмент под названием NSwag.

Типизация REST API для фронтенд разработчика - 2
Рисунок 1 Архитектура решения по генерации кода rest клиентов

На рисунке обозначены:

  • Microservice 1...N — микросервисы предоставляющие API
  • NSwag — генерация OpenAPI документа из кода API микросервиса (микросервис может быть написан на любом ЯП для которого есть инструмент для генерации документа OpenAPI)
  • NSwag — генерация кода API клиента по OpenAPI документации (есть много инструментов можно выбрать тот, что больше подходит под ваш стек технологий)
  • OpenAPI doc — OpenAPI документация сгенерированная
  • API Client 1...N — клиенты потребители данных API (могут быть реализованы на любом ЯП, который поддерживает генератор, для NSwag C# и Typescript)
  • SPA 1...N — Фронтенд приложение, в нашем случае React (NSwag поддерживает генерацию клиентов для AngularJS/Angular, React (fetch), JQuery(Promise/Callback), Aurelia)

Последовательность действий следующая:

  • Пометить API контроллер соответствующим тегом/атрибутом/декоратором зависит от ЯП, на котором реализовано API
  • Сгенерировать OpenAPI документацию по коду API
  • Сгенерировать код API клиента по OpenAPI документации
  • Интегрировать код API клиента в приложение потребитель данных API

Документация

Для того чтобы получить возможность генерации кода, нам необходимо описать типы принимаемых/возвращаемых значений контроллера API, в данном примере, где использован язык C#, с помощью атрибута SwaggerOperation мы пометили метод который будет возвращать список всех опросников на сервере, в коде клиентов метод для получения данных будет называться GetAllQuestionnaires:

[HttpGet, Route("")]
[SwaggerOperation(OperationId = "GetAllQuestionnaires")]
[SuccessResponse(typeof(IEnumerable<QuestionnaireViewModel>))]       
 public IEnumerable<QuestionnaireViewModel> Get()
 {
   var surveys = _questionnaireRepository.GetAll();
   return surveys.Select(QuestionnaireViewModel.ToViewModel).ToArray();
 }

Листинг 1 Пример С# кода, описывающего метод API

Затем с помощью NSwag мы автоматически генерируем OpenAPI документ, который будет содержать все API эндпоинты которые были помечены соответствующими атрибутами в коде бекенда.

Типизация REST API для фронтенд разработчика - 3
Рисунок 2 OpenAPI документ

Таким образом у нас получилось создать всегда актуальную автоматически обновляемую документацию нашего API.

Типизация

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

Для нашего примера документ содержит информацию о типе QuestionnaireViewModel (здесь спецификация представлена в HTML виде для удобства чтения)

Типизация REST API для фронтенд разработчика - 4
Рисунок 3 Пример модели данных в OpenAPI документе

Следующий шаг — это передать эту информацию в код фронтенд приложения.

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

Для генерации кода API клиента мы также используем NSwag. На вход он принимает OpenAPI документ и генерирует код API клиента в соответствии с заданными настройками. Для фронта рядом с полученным кодом мы добавляем package.json и отправляем в наш локальный npm регистр.

Как видно из листинга кода бэкенда (см. листинг 1), мы пометили метод контроллера с помощью атрибута

[SwaggerOperation(OperationId = "GetAllQuestionnaires")] 

OperationId заданный в атрибуте C# в нашем случае станет именем метода клиента.

Типизация REST API для фронтенд разработчика - 5
Рисунок 4 Пример использования сгенерированного API клиента

Также после генерации клиента мы получили d.ts файл который содержит соответствующие описания типов данных, показан на рисунке ниже.

Типизация REST API для фронтенд разработчика - 6
Рисунок 5 Пример описания типа данных в .d.ts файле

Теперь в коде фронтенд приложения можно пользоваться типами данных, которые экспортируются из кода API клиента и пользоваться автодополнением в редакторе кода, пример показан на рисунке ниже.

Типизация REST API для фронтенд разработчика - 7
Рисунок 6 Пример использования информации о типе данных API клиента

Также работают все соответствующие валидаторы типов данных в Typescript.

Пример на рисунках ниже.

Типизация REST API для фронтенд разработчика - 8
Рисунок 7 Пример валидации типа данных API клиента

Типизация REST API для фронтенд разработчика - 9
Рисунок 8 Пример валидации типа данных API клиента

Выводы

После применения данного подхода мы получили следующие преимущества:

  • Меньше багов связанных с типами данных
  • Меньше кода, меньше трудозатрат на отладку, тестирование, поддержку
  • Всегда актуальная документация для всех методов API для каждого из микросервисов
  • Возможность автоматизации тестирования API
  • Единая система типов для фронтенда и бэкенда

Ссылки

  • Спецификация OpenAPI
  • Сайт проекта NSWAG

Автор: chemaxa

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js