Generated Type-Safe Client SDKs Released

! This Article Contains Technical Jargon

Что нового

В нашем TypeScript migration post мы упомянули, что сгенерированные клиентские SDK появятся. Они уже здесь.

FastComments теперь поставляет официальные, типобезопасные SDK для десяти языков:

• TypeScript / JavaScript (npm)
• Python (GitHub)
• Rust (crates.io)
• Go (Go modules)
• Java (Maven)
• PHP (Composer)
• Ruby (RubyGems)
• Swift (Swift Package Manager)
• C++ (CMake)
• Nim (Nimble)

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

Как это работает

Миграция на TypeScript была предпосылкой для этого. Теперь, когда код нашего сервера полностью типизирован, мы используем our fork of TSOA для генерации спецификации OpenAPI 3.0 напрямую из наших контроллеров маршрутов. Эта спецификация передаётся в OpenAPI Generator для создания клиентских библиотек для каждого языка.

Когда API меняется, наши инструменты обнаруживают различия в спецификации, регенерируют затронутые SDK, запускают тесты для каждого языка и автоматически открывают pull request'ы. Мы создали небольшую управляющую утилиту на Nim, которая оркестрирует цикл обновления‑тестирования‑выпуска во всех десяти репозиториях.

Что находится в каждом SDK

Каждый SDK предоставляет два класса API:

• DefaultApi: аутентифицированные эндпоинты, требующие ваш API‑ключ. Используйте их на стороне сервера для модерации, управления пользователями, аналитики и массовых операций.
• PublicApi: неаутентифицированные эндпоинты, безопасные для вызова из браузеров и мобильных приложений. Они охватывают получение комментариев, их отправку, голосование и другие операции, ориентированные на клиент.

Все SDK также включают утилиты SSO для интеграции с вашей существующей системой аутентификации. SDK для TypeScript дополнительно предоставляет подписки на события в реальном времени для живого комментирования.

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

Полная документация API доступна по адресу docs.fastcomments.com. Каждый репозиторий SDK также содержит сгенерированную документацию, охватывающую все доступные методы и модели.

Для интеграции SSO см. наш SSO guide. Все десять SDK включают вспомогательные функции SSO, использующие их собственные криптографические библиотеки.

В заключение

Наличие полностью типизированного сервера упростило генерацию надёжной спецификации OpenAPI, а оттуда — создание клиентских библиотек для десяти (и когда‑нибудь большего!) языков, что в основном сводилось к построению автоматизации и улучшению наших типовых определений, чтобы они были удобны для использования, без добавления избыточной абстракции, замедляющей FastComments!

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

Удачи!