Comments 15
RAML 1.0 предлагает, конечно, классные плюшки. И IDE поверх ATOM они напилили приличную весьма
Но главная беда в том, что больше почти ни один инструмент 1.0 не поддерживает. Ни генераторы документации, ни даже web-консолька от самих Mulesoft (у них есть ветка, в которой они поддержку пилят, но она скорее сломана, чем жива)
Поэтому на 1.0 пока можно только облизываться. Ну или начать его использовать в надежде что инструменты подтянутся. ATOM-ная IDE уже более-менее с 1.0 работает
Но главная беда в том, что больше почти ни один инструмент 1.0 не поддерживает. Ни генераторы документации, ни даже web-консолька от самих Mulesoft (у них есть ветка, в которой они поддержку пилят, но она скорее сломана, чем жива)
Поэтому на 1.0 пока можно только облизываться. Ну или начать его использовать в надежде что инструменты подтянутся. ATOM-ная IDE уже более-менее с 1.0 работает
Да, я уже наступил на эти грабли. Ушёл переписывать в swagger
Swagger как open source проект, к сожалению, имеет на удивление упёртых хозяев. Очень много пул-реквестов закрывается просто потому, что «это противоречит нашей идеологии и мы больше ничего не хотим слушать».
Swagger как-то на первый взгляд показался поскучней. У RAML это просто болезнь перехода с версии на версию…
Та же ситуация.
Но после RAML Swagger кажется местами многословным, неудобным, нелогичным.
Даже без генератора документации RAML читается гораздо лучше, чем Swagger.
Но после RAML Swagger кажется местами многословным, неудобным, нелогичным.
Даже без генератора документации RAML читается гораздо лучше, чем Swagger.
Очень смутило:
usage: |
Use this annotation to declare a test case.
You may apply this annotation multiple times per location.
А почему необходимо придумывать языки для описания REST API?
Разве с этим не справится JSON?
Какие преимущества это дает?
.З.Ы. в общем одни вопросы.
usage: |
Use this annotation to declare a test case.
You may apply this annotation multiple times per location.
А почему необходимо придумывать языки для описания REST API?
Разве с этим не справится JSON?
Какие преимущества это дает?
.З.Ы. в общем одни вопросы.
так они ничего не придумали, просто заюзали YAML. YAML чуть проще читается/пишется (сугубо на мой взгляд)
JSON не для людей был придуман, а для машин. Читать его глазками то ещё «удовольствие». В отличие от YAML, который как раз задуман человеко-читаемым.
Любой инструмент должен использоваться сугубо по назначению. JSON был создан для обмена данными в вебе, а не для описания API — об этом здесь в комментариях уже писали. Поэтому при составлении документации к API поневоле приходится прибегать к помощи «костылей». Да и составлять в JSON длинные описания довольно утомительно… И не менее утомительно их читать (на это уже обратил внимание другой комментатор).
Дополнения и нововведения — это, конечно, хорошо, только без поддержки утилит типа мок-серверов и генераторов клиентского/серверного кода оно мало полезно.
Насколько я понимаю, многие библиотеки не парсят RAML самостоятельно, а опираются на официальную библиотеку raml-js-parser. Эта библиотека предназначена для RAML 0.8, но так же может и худо-бедно понимать часть RAML 1.0 при отключенной валидации. Мало кто желает получить шквал багрепортов из-за нестабильного поведения.
В свою очередь постепенно разрабатывается raml-js-parser-2, переходить на который здесь и сейчас проблематично[1] из-за несостыковок в API[2]. Я думаю что в целях экономии времени и сил — сообщество ожидает стабильной версии RAML 1.0.
Тем временем, идет разработка RAML1.0 RC2[3] и авторы уже оптимистично предполагают, что от выхода RC2 до релиза не должно пройти много времени[4].
Со своей стороны предполагаю что схемы версии 1.0 могут в организации жить до 5-10 лет, потому я не против того чтобы начать работать с текущим RC и ожидать новых инструментов в скором будущем.
[1]: github.com/raml2html/raml2html/issues/156#issuecomment-159296208
[2]: github.com/raml-org/raml-js-parser-2/issues/11
[3]: github.com/raml-org/raml-spec/tree/raml-10-rc2
[4]: raml.org/blogs/update-raml-10-current-status
В свою очередь постепенно разрабатывается raml-js-parser-2, переходить на который здесь и сейчас проблематично[1] из-за несостыковок в API[2]. Я думаю что в целях экономии времени и сил — сообщество ожидает стабильной версии RAML 1.0.
Тем временем, идет разработка RAML1.0 RC2[3] и авторы уже оптимистично предполагают, что от выхода RC2 до релиза не должно пройти много времени[4].
Со своей стороны предполагаю что схемы версии 1.0 могут в организации жить до 5-10 лет, потому я не против того чтобы начать работать с текущим RC и ожидать новых инструментов в скором будущем.
[1]: github.com/raml2html/raml2html/issues/156#issuecomment-159296208
[2]: github.com/raml-org/raml-js-parser-2/issues/11
[3]: github.com/raml-org/raml-spec/tree/raml-10-rc2
[4]: raml.org/blogs/update-raml-10-current-status
Народ, а покажите какие-нибудь реальные примеры API, описанных в RAML? И сгенерированные html'ки тоже было бы интересно увидеть.
И Самый главный вопрос: как поддерживать актуальность RAML-спецификаций и кода, который этот самый API реализует? Насколько я понял, надо только ручками после изменений апишки править RAML…
И Самый главный вопрос: как поддерживать актуальность RAML-спецификаций и кода, который этот самый API реализует? Насколько я понял, надо только ручками после изменений апишки править RAML…
Sign up to leave a comment.
RAML 1.0: обзор нововведений