Именно, поэтому синтаксис OpenAPI выглядит нагруженнее, он просто содержит больше информации для большей функциональности
Никак не могу согласиться, на практике даже супер навороченные API на JSight выглядят гораздо проще, чем на OpenAPI. Более того, чем сложнее API, тем больше преимуществ у JSight.
Сергей, спасибо за подробный и вдумчивый комментарий!
Отвечу по порядку:
Понимаю ваше изумление. Разработка нового языка и инструментов к нему стоит на два порядка дороже, чем настройка бизнес-процессов или проектирование API, даже вдесятером. Вряд ли можно порекомендовать решать проблемы с API таким образом. JSight, конечно, нужно рассматривать как отдельный проект с отдельным финансированием. На поддержку также средства есть, кроме того есть расчёт на open-source сообщество.
OpenAPI — классный язык, мы не спорим. Просто хочется ещё лучше :)
Верно, в этой статье речь идёт больше о языке создания спецификаций API. Документацию по JSight-спецификации можно сгенерировать в нашем онлайн-едиторе: https://editor.jsight.io (там есть кнопочки "Export" и "Download"). В этой документации можно включить табличное описание либо с помощью кнопки "Table View" для каждой схемы отдельно, либо сразу для всех схем в настройках.
Да. Поддержка других видов API — это один из наших главных принципов. Мы сразу же проектировали язык не только под стиль REST, но и под стили RPC и Event-bus (асинхронные протоколы). Вот, например, как выглядит JSON-RPC API:
JSIGHT 0.3
URL /rpc-api
Protocol json-rpc-2.0
Method add // Addition.
Params
{
"par1": 123.5, // Parameter 1.
"par2": -1.0 // Parameter 2.
}
Result
122.5 // Result of addition.
И все-таки, никто не знает, адекватно описание API или устарело. Я как архитектор скажу так: когда приходишь на новый проект и просишь документацию, то практически никогда (!) она не соответствует реальности.
Как архитектору принимать решения о трансформации архитектуры, если он даже не может понять, как сейчас система работает?
Кирилл, спасибо! Можете подробнее раскрыть, что вы имеете в виду под шаблонами/дженериками? На каком-нибудь простом примере. У нас есть поддержка макросов, возможно, их получится расширить до дженериков, но нужно понять, что именно вы имеете в виду.
Кодогенерация будет обязательно. У нас на ближайшее будущее запланированы две большие фичи: конвертер в OpenAPI и обратно; кодогенератор.
Верно! Но «достаточная автоматизация» — это не такое уж частое явление в реальных проектах. А JSight неплохо работает, даже когда ничего не автоматизировано. Достаточно только поставить валидатор, который будет проверять все запросы и ответы.
Согласен, что машиночитаемость JSight сильно уступает OpenAPI, мягко выражаясь) Но у нас уже есть библиотека, которая парсит JSight-текст и выдаёт аккуратное json-описание (https://github.com/jsightapi/jsight-server). К тому же, планируется выпуск конвертера в OpenAPI.
Замечательная идея! Хочется пожелать авторам успеха.
Спасибо за вопрос! Я бы сказал, что мы разработали не еще одну, а первую в мире спецификацию, которую можно признать годной для описания API вручную)
Никак не могу согласиться, на практике даже супер навороченные API на JSight выглядят гораздо проще, чем на OpenAPI. Более того, чем сложнее API, тем больше преимуществ у JSight.
Прекрасно! Но это, всё же, Code First подход, если я правильно понимаю.
Сергей, спасибо за подробный и вдумчивый комментарий!
Отвечу по порядку:
Понимаю ваше изумление. Разработка нового языка и инструментов к нему стоит на два порядка дороже, чем настройка бизнес-процессов или проектирование API, даже вдесятером. Вряд ли можно порекомендовать решать проблемы с API таким образом. JSight, конечно, нужно рассматривать как отдельный проект с отдельным финансированием. На поддержку также средства есть, кроме того есть расчёт на open-source сообщество.
Один из наших принципов — полное соответствие функциональности OpenAPI. В статье мы описали основную идею, и не рассказывали о нюансах языка. Раз уж зашла речь, скажу, что JSight обладает всеми must-have фичами, и даже больше: пользовательские типы, макросы, ссылки на файлы (include), наследование (allOf), вариативность (or), регулярные выражения, перечисления (enums), пользовательские комментарии, заголовки, query-запросы, маркдаун, и т. д. Title и Description тоже, соответственно, есть. Всё это можно найти в спецификации языков JSight API и JSight Schema.
OpenAPI — классный язык, мы не спорим. Просто хочется ещё лучше :)
Верно, в этой статье речь идёт больше о языке создания спецификаций API. Документацию по JSight-спецификации можно сгенерировать в нашем онлайн-едиторе: https://editor.jsight.io (там есть кнопочки "Export" и "Download"). В этой документации можно включить табличное описание либо с помощью кнопки "Table View" для каждой схемы отдельно, либо сразу для всех схем в настройках.
Да. Поддержка других видов API — это один из наших главных принципов. Мы сразу же проектировали язык не только под стиль REST, но и под стили RPC и Event-bus (асинхронные протоколы). Вот, например, как выглядит JSON-RPC API:
Вот более подробный пример с JSON-RPC: https://editor.jsight.io/r/aL9XejZ/1.
Интересно, спасибо)
Так у нас же не "примерчик на json", а полноценный язык спецификации контракта.
Да, понял, отличная идея! Спасибо, подумаем)
Api Blueprint для описания типов данных использует ту же самую громоздкую JSON-Schema, что и OpenAPI. Поэтому нам он тоже не подошёл.
И все-таки, никто не знает, адекватно описание API или устарело. Я как архитектор скажу так: когда приходишь на новый проект и просишь документацию, то практически никогда (!) она не соответствует реальности.
Как архитектору принимать решения о трансформации архитектуры, если он даже не может понять, как сейчас система работает?
Кирилл, спасибо! Можете подробнее раскрыть, что вы имеете в виду под шаблонами/дженериками? На каком-нибудь простом примере. У нас есть поддержка макросов, возможно, их получится расширить до дженериков, но нужно понять, что именно вы имеете в виду.
Кодогенерация будет обязательно. У нас на ближайшее будущее запланированы две большие фичи: конвертер в OpenAPI и обратно; кодогенератор.
Также большая просьба поставить нам звезду на Гитхабе :)
Зато у GraphQL есть другие проблемы) Вот, например, недавняя статья на хабре: GraphQL: от восторга до разочарования.
Верно, многие так делают. Только никто не может сказать, актуально это описание, или устарело.
Если вам понравилось, поставьте нам звезду на гитхабе, очень поможете)
Типизация в языке JSight, конечно, есть, просто в статье мы об этом не писали.
Вот пример с пользовательским типом:
Тот же пример в редакторе: https://editor.jsight.io/r/KBnr8B1/2
Верно! Но «достаточная автоматизация» — это не такое уж частое явление в реальных проектах. А JSight неплохо работает, даже когда ничего не автоматизировано. Достаточно только поставить валидатор, который будет проверять все запросы и ответы.
Статья как раз и написана про Swagger. Только в 2016 году язык «Swagger» был переименован в «OpenAPI».
Пока ещё не решаем, но это в ближайших планах, конечно. Новости смотрите на сайте проекта: https://jsight.io/
Согласен, что машиночитаемость JSight сильно уступает OpenAPI, мягко выражаясь) Но у нас уже есть библиотека, которая парсит JSight-текст и выдаёт аккуратное json-описание (https://github.com/jsightapi/jsight-server). К тому же, планируется выпуск конвертера в OpenAPI.
Да, транслятор туда и обратно планируется.