📄
TypeSpec: новый язык для API или очередная мода?На Analyst Days 22
Руслан Папенко рассказывал про TypeSpec от Microsoft. Тема действительно горячая, но в индустрии любят волны хайпа — был RAML, был API Blueprint, теперь вот TypeSpec.
Я послушала, сравнила с OpenAPI и альтернативами. Делюсь выжимкой для прагматиков.
🧐
Что такое TypeSpecTypeSpec — это
предметно-ориентированный язык (DSL) для описания API. Он не заменяет OpenAPI напрямую, а компилируется в него (и не только). Релиз — апрель 2024, Microsoft, открытый исходный код.
Синтаксис напоминает TypeScript. Вы описываете модели данных, операции, а генератор выдаёт:
➖ спецификацию OpenAPI (YAML/JSON)
➖ документацию (например, HTML/Markdown)
➖ клиентские SDK на нескольких языках (основная поддержка TypeScript, .NET, Java, Python)
➖ генерация серверных заглушек (ограничена в основном .NET и JavaScript)
Звучит круто. Но давайте по фактам.
⚔️
Почему OpenAPI уже не тортПрезентация Руслана на Analyst Days и мнения инженеров со всего мира сходятся: OpenAPI, при всей своей популярности, доставляет много боли.
❌
Проблема №1: Нечеловеческий синтаксисOpenAPI использует YAML или JSON — форматы, удобные для машин, но не для людей. Описания получаются многословными, часто похожими на «спагетти» из вложенных блоков. А разработчики с усталостью вспоминают, что им постоянно приходится подсматривать в документацию даже для простых вещей.
❌
Проблема №2: Сложность на масштабеЕсли в проекте больше пары десятков эндпоинтов, спецификация превращается в гигантский файл (условно на 2000-3000+ строк). Отладка и поддержка такой простыни становятся крайне трудоёмкими.
❌
Проблема №3: Design-First страдаетOpenAPI создавался как формат
документации готового API, не спорю, что далее он уже развивалась как формат для
Design first. Если мы говорим про объёмные enterprise-системы, то вносить точечные изменения в разросшиеся YAML-файлы — пытка, да — есть визуальные редакторы...
💡
Чем TypeSpec лучшеЕсли взять простой пример (приводить не буду, был на конференции и полно в "интернетах"), то разница очевидна, разница будет раза в 3 по количеству строк.
✅ Композиция без боли
✅ Не привязан к REST
Описав модели, можно сгенерировать не только OpenAPI, но и gRPC (protobuf), AsyncAPI для сообщений, даже GraphQL.
✅ Один источник правды
Меняете модель — перегенерировали клиента, документацию, моки. Забыли обновить документацию вручную — не ваш случай.
🔄
Полная картина: какие есть альтернативыВопрос рёбром: инновация или тренд? Хочу расширить контекст. TypeSpec — не единственный игрок на поле «API как код».
1️⃣ Design FirstПлатформы вроде
Apidog или
Stoplight Studio отходят от сырого YAML . Они предлагают визуальные редакторы, схемы перетаскиванием, авто-моки и документацию на лету.
Плюсы: GUI понятен даже нетехническим специалистам.
Минусы: GitHub не всегда удобен для ревью тяжелых PNG.
2️⃣ Code FirstИнструменты вроде
Swaggo (Go) или
SpringDoc (Java) парсят комментарии в коде и генерируют OpenAPI.
Плюсы: Документация всегда соответствует коду.
Минусы: Код обрастает аннотациями, сложно охватить всю систему целиком.
3️⃣ Альтернативные DSL и Protocol BuffersЕсли TypeSpec от Microsoft, то
Smithy от Amazon (используется в AWS) существует дольше.
Protocol Buffers (protobuf) от Google — вообще тяжёлая артиллерия для микросервисов.
Плюсы: Скорость, строгая типизация, поддержка в любом языке.
Минусы: Бинарный протокол, REST вы получаете через транзакцию.
🎓
Моё резюмеИнструмент действительно
зрелый, но ещё не полностью готов для промышленного использования всеми командами в любом масштабе.
Пробовали уже TypeSpec? Или всё ещё на YAML? 👇#Инструменты