Comments 39
>Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости… Но, увы, пока что такой возможности нет.
Как нет? А схемы и $ref? (сотая строка в примере editor.swagger.io )
И в догонку: документация это хорошо, а валидация данных по RAML-схемам есть?
Как нет? А схемы и $ref? (сотая строка в примере editor.swagger.io )
И в догонку: документация это хорошо, а валидация данных по RAML-схемам есть?
>>>>валидация данных по RAML-схемам есть?>>>>
Есть. Вот ссылка на инструмент для валидации: www.npmjs.com/package/raml-validate
Есть. Вот ссылка на инструмент для валидации: www.npmjs.com/package/raml-validate
Swagger/Swashbuckle
И в связи с этим возникает вопрос: так чем же, все-таки, RAML принципиально лучше/удобнее?
И в связи с этим возникает вопрос: так чем же, все-таки, RAML принципиально лучше/удобнее?
Чем лучше? Отвечаю по пунктам?
1. Гораздо более простым и логичным синтаксисом описаний.
2. Возможностью расписать в документации гораздо большее количество параметров, чем в том же swagger и, самое главное, сделать это при помощи более простых и удобных конструкций (сравните те же описания схем безопасности или query-параметров).
3. Расширенными (по сравнению с тем же swagger) возможностями использования include'ов и наследования, благодаря чему документация получается более компактной и элегантной.
Единственное, в чём RAML пока что проигрывает Swagger — недостаточное количество разрабатываемых сообществом инструментов. Но это — дело наживное.
1. Гораздо более простым и логичным синтаксисом описаний.
2. Возможностью расписать в документации гораздо большее количество параметров, чем в том же swagger и, самое главное, сделать это при помощи более простых и удобных конструкций (сравните те же описания схем безопасности или query-параметров).
3. Расширенными (по сравнению с тем же swagger) возможностями использования include'ов и наследования, благодаря чему документация получается более компактной и элегантной.
Единственное, в чём RAML пока что проигрывает Swagger — недостаточное количество разрабатываемых сообществом инструментов. Но это — дело наживное.
Для RAML есть инструменты, позволяющие автоматически генерить документацию в этом формате для уже существующего API (желательно — на лету)?
Насколько мне известно, пока что нет.
Угу, потому что RAML — это «сначала контракт, потом все остальное». А я вот совершенно не хочу так писать, я хочу иметь (аннотированное) серверное API, по которому генерятся описания в произвольных форматах. И вот тут Swagger работает прекрасно (потому что для него есть соответствующий инструментарий под мою платформу).
(хотя, конечно, в нем встречаются вещи, которые сложно выразить)
(хотя, конечно, в нем встречаются вещи, которые сложно выразить)
Разные задачи — разные инструменты.
Т.е. вы не проектируете, а сразу пишете код?
Почему же, я проектирую, просто код — это и есть проект. Code is the documentation, я не хочу думать о том, как содержать их в соответствии друг с другом.
Согласен. Для проектов на JAX-RS использую maven-javadoc-plugin вместе с swagger-doclet, Он генерирует swagger-документацию по JavaDoc. Помимо обычных аннотаций используются специфические дополнительные аннотации, которые не мешают читать код, но помогают уточнить документацию. Дополнительный бонус — приучает писать полноценные комментарии :)
Учитывая что эти форматы чаще употребляются сриптами чем читаются человеком (зачем это читать если можно посмотреть что в UI нагенерили для каждого endpoint) то логичность синтаксиса — это вопрос второй.
А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.
Ну и набирает обороты он быстрее и дальше это будет только ускоряться, как снежный ком.
Например и Microsoft (Azure API Management, API Apps) и Amazon ( AWS API Management import) используют Swagger, а не RAML или API Blueprint.
Для RAML есть генераторы клиентов, как например AutoRest для .NET?
А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.
Ну и набирает обороты он быстрее и дальше это будет только ускоряться, как снежный ком.
Например и Microsoft (Azure API Management, API Apps) и Amazon ( AWS API Management import) используют Swagger, а не RAML или API Blueprint.
Для RAML есть генераторы клиентов, как например AutoRest для .NET?
>>>>Учитывая что эти форматы чаще употребляются сриптами чем читаются человеком (зачем это читать если можно посмотреть что в UI нагенерили для каждого endpoint) то логичность синтаксиса — это вопрос второй. >>>>
Даже для скриптов лучше писать в простом формате и без лишних «костылей».
>>>>Для RAML есть генераторы клиентов, как например AutoRest для .NET?>>>>
Есть, но пока что они находятся в очень «сыром» состоянии.
>>>>А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.>>>>>
За RAML стоит не одна компания. В разработке спецификаций принимали участие представители Cisco, PayPal, BoxInc. Насчёт коммьюнити — оно уже формируется (см., например, здесь: raml.org/projects.html)
Даже для скриптов лучше писать в простом формате и без лишних «костылей».
>>>>Для RAML есть генераторы клиентов, как например AutoRest для .NET?>>>>
Есть, но пока что они находятся в очень «сыром» состоянии.
>>>>А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.>>>>>
За RAML стоит не одна компания. В разработке спецификаций принимали участие представители Cisco, PayPal, BoxInc. Насчёт коммьюнити — оно уже формируется (см., например, здесь: raml.org/projects.html)
Даже для скриптов лучше писать в простом формате и без лишних «костылей».
Вот только скриптам совершенно все равно на, скажем, дублирование, и поэтому наследование и трейты им уже не так нужны. А если исходить из того, что описание и генерится автоматически — тогда и вопрос противоречивости не встает.
reStructuredText, как inline-документация, так и документация в целом.
активно использую формат blueprint, всё, что описано в статье для RAML есть и в блупринте. Результат получается красивый и для пользователя удобный, но вот для писателя формат api blueprint немного корявенький, очень неудобно, например, следовать через чур строгим требованиям по количеству пробелов и табуляций: список параметров — значит два таба, ещё что-то — четыре таба и т.д. Это кажется немного излишним, ведь распарсить явно и так всё получится.
У нас на PHP проекте API описано на WSDL, это описание работает и для первичной валидации. Документацию получаем с помощью XSLT преобразования WSDL-ки. Подход хорошо себя зарекомендовал. Но приведенный в статье набор инструментов вокруг RAML впечатляет.
А у вас REST API или SOAP API?
Именно REST
А как вы в wsdl описали rest-ресурсы и, особенно, http-семантику?
Пример, входные параметры:
Пример части с документацией:
<xs:element name="accountRequestData">
<xs:complexType>
<xs:sequence>
<xs:annotation>
<xs:documentation source="id" xml:lang="ru">Идентификатор записи</xs:documentation>
<xs:documentation source="inn" xml:lang="ru">ИНН</xs:documentation>
<xs:documentation source="is_active" xml:lang="ru">Счет активен</xs:documentation>
<xs:documentation source="user_id" xml:lang="ru">Пользователь</xs:documentation>
</xs:annotation>
<xs:element name="id" type="xs:int" />
<xs:element name="inn" type="xs:string" minOccurs="0" />
<xs:element name="is_active" type="ns:BOOL" />
<xs:element name="user_id" type="xs:int" />
</xs:sequence>
</xs:complexType>
</xs:element>
Пример части с документацией:
<operation name="methodAccount">
<documentation type="map">
<name>Вставка и изменение счета</name>
<status>works</status>
<speed_level>fast</speed_level>
<quota_per_second>20</quota_per_second>
<rest call="account" httpMethod="POST"/>
</documentation>
</operation>
Это ваше собственное расширение или какой-то публичный фреймворк?
Фрейморк-то Yii2, но он тут ни при чем. Работа с WSDL через \DOMDocument.
Ну то есть ваше собственное расширение.
Методы для работы с \DOMDocument, кстати, вынесены в отдельную библиотеку, или скорее даже фреймворк, его у нас соседняя команда сделала, но он к сожалению не публичный.
Слишком сложно…
Кстати, а существуют ли какие-нибудь генераторы интерактивной документации для WSDL?
Кстати, а существуют ли какие-нибудь генераторы интерактивной документации для WSDL?
Не знаю про интеграктивную документацию, а вот клиенты на основании wsdl строятся, в том числе и песочницы.
Не сказал бы, что слишком сложно. По сути, за валидацию отвечает несколько строк. Если упрощенно, то примерно так:
Т.е. в PHP для этого готовые инструменты есть.
Или громоздко описания выглядят? Ну, возможно. Меня не напрягает, думаю, дело привычки.
Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.
$validator = new \DOMDocument( '1.0', 'UTF-8' );
$validator->loadXML( $xml );
if (!$validator->schemaValidateSource($xsd)) {
...
}
Т.е. в PHP для этого готовые инструменты есть.
Или громоздко описания выглядят? Ну, возможно. Меня не напрягает, думаю, дело привычки.
Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.
А если у вас данные не в xml гуляют?
Бывает и такое. В этом случае просто JSON преобразуем в XML и направляем на валидацию
И вас не смущает, что вы в этом случае требуете, чтобы JSON имел конкретную последовательность элементов, чего он гарантировать не может и не будет?
(ну и вообще это не вполне однозначное преобразование, если вы только не накладываете на xml и xsd дополнительных ограничений)
(ну и вообще это не вполне однозначное преобразование, если вы только не накладываете на xml и xsd дополнительных ограничений)
Не смущает, на этот случай был придуман велосипед — переданные параметры сортируются в алфавитном порядке. В WSDL тоже параметры описаны в алфавитном порядке. Но, как оказалось, на этот случай есть готовое простое решение — вместо sequence можно использовать all в WSDL.
Некоторые ограничения на формат есть, но по практике скажу, что трудностей это не создает.
Некоторые ограничения на формат есть, но по практике скажу, что трудностей это не создает.
Да, сами описания выглядят несколько громоздко, что немного напрягает.
>>>Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.>>>>
Я ничего не имею против этого подхода. Задавая свой вопрос, я никаких философских аспектов затрагивать не хотел. Мне действительно интересно, насколько сейчас распространён WSDL, как он поддерживается сообществом, какие есть вспомогательные инструменты.
>>>Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.>>>>
Я ничего не имею против этого подхода. Задавая свой вопрос, я никаких философских аспектов затрагивать не хотел. Мне действительно интересно, насколько сейчас распространён WSDL, как он поддерживается сообществом, какие есть вспомогательные инструменты.
Присоединяюсь к вопросу.
Привет бывшему коллеге, все верно — в тот период, когда API, в «организации», в которой мы трудились, разрабатывался о RAML-e не могло быть и речи, а swagger знали немногие. Помню даже, что написал авто-генератор, но под него надо было в бд описывать/складывать сущности, а так как всем было лень — никто его так и не заюзал =)
Сейчас прогресс ушел вперед — есть не только форматы описания, но и форматы вывода данных — JSON API например, откровенно говоря, устав от многолетних наблюдений вело-костылей — решил запрогать авто-генератор на основе RAML, с полной поддержкой JSON API (можно отключать) под Laravel5.x, в частности под laravel-module, если кому-нибудь интересно — https://github.com/RJAPI/raml-json-api (буду рад контрибам и предметной критике — развитие наше все).
Данный подход «сцепления» входных параметров на RAML-генератор и на выходе — JSON API сущностей, отлично прижился, в крупной компании (~1500чел.), в которой работаю сейчас, разрабатывали с 3-мя коллегами (программистами-инженерами), но тут пилили под Yii2.
Сейчас прогресс ушел вперед — есть не только форматы описания, но и форматы вывода данных — JSON API например, откровенно говоря, устав от многолетних наблюдений вело-костылей — решил запрогать авто-генератор на основе RAML, с полной поддержкой JSON API (можно отключать) под Laravel5.x, в частности под laravel-module, если кому-нибудь интересно — https://github.com/RJAPI/raml-json-api (буду рад контрибам и предметной критике — развитие наше все).
Данный подход «сцепления» входных параметров на RAML-генератор и на выходе — JSON API сущностей, отлично прижился, в крупной компании (~1500чел.), в которой работаю сейчас, разрабатывали с 3-мя коллегами (программистами-инженерами), но тут пилили под Yii2.
Ой, простите ссылку забыл выделить, а комент не могу отредактировать — https://github.com/RJAPI/raml-json-api
Вообще RAML спецификация как и инструменты для работы с ним, мягко говоря, не особо обновляются в последнее время (около года).
Его удобно использовать, чтобы быстро спроектировать REST API и окинуть взглядом как все вместе выглядит.
Из того что не хватает в версии 0.8:
1. Поддержка массивов: some_path/1,2,3,5.json Никак это нельзя описать, только если отдельное описание вставлять.
2. Поддерживает только '=' в query string. Т.е. нельзя описать что-то типа: path?star<2015-08-27T08:30:00.000Z
Его удобно использовать, чтобы быстро спроектировать REST API и окинуть взглядом как все вместе выглядит.
Из того что не хватает в версии 0.8:
1. Поддержка массивов: some_path/1,2,3,5.json Никак это нельзя описать, только если отдельное описание вставлять.
2. Поддерживает только '=' в query string. Т.е. нельзя описать что-то типа: path?star<2015-08-27T08:30:00.000Z
Sign up to leave a comment.
Пишем документацию API при помощи RAML