📄TypeSpec: новый язык для API или очередная мода?
На Analyst Days 22 Руслан Папенко рассказывал про TypeSpec от Microsoft. Тема действительно горячая, но в индустрии любят волны хайпа — был RAML, был API Blueprint, теперь вот TypeSpec.
Я послушала, сравнила с OpenAPI и альтернативами. Делюсь выжимкой для прагматиков.
🧐 Что такое TypeSpec
TypeSpec — это предметно-ориентированный язык (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? 👇
#Инструменты
На Analyst Days 22 Руслан Папенко рассказывал про TypeSpec от Microsoft. Тема действительно горячая, но в индустрии любят волны хайпа — был RAML, был API Blueprint, теперь вот TypeSpec.
Я послушала, сравнила с OpenAPI и альтернативами. Делюсь выжимкой для прагматиков.
🧐 Что такое TypeSpec
TypeSpec — это предметно-ориентированный язык (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? 👇
#Инструменты