Обладает ли преимуществами RAML перед SWAGGER (Open Api) в 2018 году?
Выбирая систему документации, выбрали RAML, ввиду обещания меньшего дублирования.
Однако обратил внимание что по RAML очень мало СВЕЖЕЙ документации и статей, инструменты которые были для него разработаны очень многие не развивались уже 2-3+ года, 1.0 версия поддерживается слабо инструментами (в т.ч. для PostMan пришлось генерировать RAML=>Swagger).
Swagger еще не пользовались, только погружаемся в системы документации.
В связи с этим вопрос: имеет ли смысл использовать RAML в 2018, возможно SWAGGER уже пофиксил те недостатки из-за которых создался RAML как более расширенная альтернатива?
spaceatmoon, Нужно не API на основе документации создавать, а автоматически генерировать документацию на основе кода. Именно для этого swagger и создан.
neatsoft, позвольте с вами попробовать поспорить. Сейчас популярен подход API FIRST, который позволяет фронту со SPA вынесенными в отдельный микросервис не ждать бекендера для начала работы и параллелить фронт/бек сразу, что очень актуально в текущих рыночных условиях и требованиях запускать проекты очень быстро.
Текущие RAML инструменты позволяют генерировать PHP & JS прослойку на основе документации, что может дать хороший низкий старт для проекта.
Иван Николаевич, Согласен, top-down тоже имеет право на жизнь. Но в тех проектах, где он действительно нужен, обычно есть опытный Software Architect / API Designer, который и так прекрасно знает разницу между RAML и Swagger.
Проектирование хороших API, которые потом не приходится переделывать для повышения производительности или обеспечения согласованности, это выдающийся навык, которым обладают единицы. Поэтому в большинстве случаев bottom-up это более жизнеспособная концепция.
btw, Апишки не обязательно писать, их можно генерировать. И уже на их основе создавать OpenAPI спецификации, которые фронты будут видеть в Swagger UI. Если Software Architect не брезгует написанием кода, то такой подход не только сэкономит время, но и очень сильно упростит сопровождение проекта, т.к. в нём будет меньше мест для типичных программерских ошибок. Некоторые эндпоинты всё-таки придётся создать вручную, но со значительной частью апи можно будет начать работать практически сразу, причём не с фейковыми данными, а с реальной бд.
Почему-то никто всерьёз не воспринимает параллельное развитие как описания API, так и кода, вплоть до того, что различные иннтерфейсы (в статически типизированных языках) или тесты генерируются прямо при сборке проекта, и прямо при сборке же проверяется, что код сервиса (ну, например, контроллер для MVC-фреймворков) действительно реализует описанный интерфейс. Тут вовсе не обязательно всё API написать заранее, скорее наоборот, поощряется развитие за счёт дополнительной проверки корректности.
Может кто-то сталкивался с конкретными проблемами?
Станислав Макаров, просто всем (большинству) плевать и охота скроить время. Крупные организации все api first, но для них это настолько очевидно что они об этом и не говорят особо.
Станислав Макаров, Это работает с примитивной кодогенерацией, но в реальной жизни встречаются существенно более сложные случаи, когда кодогенератор - это отдельный проект, зачастую написанный на другом языке, который формирует не только интерфейсы, но и сами методы. С помощью одной лишь документации такое сделать не получится.
Waterfall, со всеми присущими ему подходами и инструментами, до сих пор активно используется в некоторых сферах, и там альтернатив ему нет. Но в массовом сегменте это прямой путь к коммерческому провалу из-за отсутствия гибкости и недостаточной динамичности.
RAML - top-down, Swagger - bottom-up, они совершенно разные.
Использую Swagger для автоматического создания документации на основе кода и комментариев. Есть некоторые шероховатости, но в целом всё работает. Позволяет экономить уйму времени, и легко поддерживать документацию в актуальном состоянии.
Документация обычно и так есть - спецификация проекта. И на начальном этапе лучше побольше времени уделить описанию бизнес задач и граничных условий, чтобы не обнаружить через несколько месяцев (или даже лет) что в текущем виде ни апи, ни документация больше никому не нужны, т.к. систему нужно полностью переделывать из-за какой-то маленькой, но очень важной детали (несколько реальных случаев из жизни - приходилось разгребать результаты "труда" других архитекторов и разработчиков).
Спроектировать начисто - сложно, многие аспекты становятся очевидны лишь в процессе. Есть уникумы, которые уже успели зафейлить не один десяток проектов, и поэтому хорошо знают где "подстелить соломки", но это не относится к массовому рынку, т.к. сейчас колоссальный дефицит кадров.
В реальной жизни на поддержание документации в актуальном состоянии всегда забивают, т.к. сделать это может только грамотный разработчик, что выливается немалые дополнительные расходы и снижение мотивации в коллективе. Код писать гораздо интереснее чем доки, т.к. постоянно узнаёшь что-то новое, не прикладывая к этому больших усилий. Поэтому от документирования все отлынивают.
Что касается автоматизации, из описания код можно сгенерировать только один раз, а документацию из кода - хоть каждый день, и для этого не нужно прикладывать никаких усилий.
При top-down подходе излишняя формализация создаёт дополнительную бюрократию, и увеличивает затраты времени на согласования. При bottom-up стабильность документации обеспечивается стабилизацией самого АПИ - ключевая функциональность покрывается тестами, и никакие изменения не могут попасть в прод, если они эту функциональность ломают.
Единственное место для "наоборот" - это команды с очень опытным архитектором, который при проектировании АПИ заранее может предусмотреть все подводные камни, и очень неопытными бэкендерами, которые не в состоянии самостоятельно вникать в бизнес задачи и нести ответственность за свои решения.
Станислав Макаров, Есть, но зачем возить мебель в седане или людей в грузовике, если для каждой из этих задач есть свои инструменты? OpenAPI - это не только Swagger, это ещё и большое количество инструментов, которые значительно упрощают работу с ним. Большинство из них рассчитаны именно на bottom-up.
RAML в 2018 - довольно рискованная инвестиция времени (т.к. непонятно жив ли он), а это главное что должно интересовать разработчика, который ответственно относится к своей жизни. По этой причине, например, многие отказываются от Trio в пользу asyncio, или выбирают Go вместо Rust.
Раньше RAML был интереснее за счёт развитой системы типов данных: ЕМНИП, ранее первые версии сваггера/openapi поддерживали только встраивание JSON-схемы, теперь же вроде OpenAPI доразвился в этом плане, так что он выглядит сопоставимым по возможностям, но значительно менее рисковым.
Простой
Сложный
Простой
