yuhenobi Aug 24 2015 at 14:51

Пишем документацию API при помощи RAML

10 min

76K

Selectel corporate blogWebsite development*API*

Tutorial

+28

Comments 39

iSage Aug 24 2015 at 14:59

>Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости… Но, увы, пока что такой возможности нет.

Как нет? А схемы и $ref? (сотая строка в примере editor.swagger.io )

И в догонку: документация это хорошо, а валидация данных по RAML-схемам есть?

AndreiYemelianov Aug 24 2015 at 15:26

>>>>валидация данных по RAML-схемам есть?>>>>

Есть. Вот ссылка на инструмент для валидации: www.npmjs.com/package/raml-validate

lair Aug 24 2015 at 15:14

Swagger/Swashbuckle

И в связи с этим возникает вопрос: так чем же, все-таки, RAML принципиально лучше/удобнее?

AndreiYemelianov Aug 24 2015 at 15:35

Чем лучше? Отвечаю по пунктам?

1. Гораздо более простым и логичным синтаксисом описаний.
2. Возможностью расписать в документации гораздо большее количество параметров, чем в том же swagger и, самое главное, сделать это при помощи более простых и удобных конструкций (сравните те же описания схем безопасности или query-параметров).
3. Расширенными (по сравнению с тем же swagger) возможностями использования include'ов и наследования, благодаря чему документация получается более компактной и элегантной.

Единственное, в чём RAML пока что проигрывает Swagger — недостаточное количество разрабатываемых сообществом инструментов. Но это — дело наживное.

lair Aug 24 2015 at 15:36

Для RAML есть инструменты, позволяющие автоматически генерить документацию в этом формате для уже существующего API (желательно — на лету)?

-1

AndreiYemelianov Aug 24 2015 at 15:51

Насколько мне известно, пока что нет.

lair Aug 24 2015 at 15:55

Угу, потому что RAML — это «сначала контракт, потом все остальное». А я вот совершенно не хочу так писать, я хочу иметь (аннотированное) серверное API, по которому генерятся описания в произвольных форматах. И вот тут Swagger работает прекрасно (потому что для него есть соответствующий инструментарий под мою платформу).

(хотя, конечно, в нем встречаются вещи, которые сложно выразить)

AndreiYemelianov Aug 24 2015 at 16:11

Разные задачи — разные инструменты.

lair Aug 24 2015 at 16:13

Занятно, что при этом с точки зрения клиента задача-то одна.

clickfreak Aug 24 2015 at 22:17

Т.е. вы не проектируете, а сразу пишете код?

lair Aug 24 2015 at 22:40

Почему же, я проектирую, просто код — это и есть проект. Code is the documentation, я не хочу думать о том, как содержать их в соответствии друг с другом.

romychs Aug 25 2015 at 12:29

Согласен. Для проектов на JAX-RS использую maven-javadoc-plugin вместе с swagger-doclet, Он генерирует swagger-документацию по JavaDoc. Помимо обычных аннотаций используются специфические дополнительные аннотации, которые не мешают читать код, но помогают уточнить документацию. Дополнительный бонус — приучает писать полноценные комментарии :)

centur Aug 24 2015 at 16:51

Учитывая что эти форматы чаще употребляются сриптами чем читаются человеком (зачем это читать если можно посмотреть что в UI нагенерили для каждого endpoint) то логичность синтаксиса — это вопрос второй.

А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.

Ну и набирает обороты он быстрее и дальше это будет только ускоряться, как снежный ком.
Например и Microsoft (Azure API Management, API Apps) и Amazon ( AWS API Management import) используют Swagger, а не RAML или API Blueprint.

Для RAML есть генераторы клиентов, как например AutoRest для .NET?

AndreiYemelianov Aug 24 2015 at 17:48

>>>>Учитывая что эти форматы чаще употребляются сриптами чем читаются человеком (зачем это читать если можно посмотреть что в UI нагенерили для каждого endpoint) то логичность синтаксиса — это вопрос второй. >>>>

Даже для скриптов лучше писать в простом формате и без лишних «костылей».

>>>>Для RAML есть генераторы клиентов, как например AutoRest для .NET?>>>>
Есть, но пока что они находятся в очень «сыром» состоянии.

>>>>А вот коммунити — это наживается непросто. За RAML стоит одна компания, как и за API Blueprint. Swagger старается вовлечь сообщество в стандарт.>>>>>

За RAML стоит не одна компания. В разработке спецификаций принимали участие представители Cisco, PayPal, BoxInc. Насчёт коммьюнити — оно уже формируется (см., например, здесь: raml.org/projects.html)

lair Aug 24 2015 at 17:50

Даже для скриптов лучше писать в простом формате и без лишних «костылей».

Вот только скриптам совершенно все равно на, скажем, дублирование, и поэтому наследование и трейты им уже не так нужны. А если исходить из того, что описание и генерится автоматически — тогда и вопрос противоречивости не встает.

BasicWolf Aug 24 2015 at 20:08

reStructuredText, как inline-документация, так и документация в целом.

catanfa Aug 24 2015 at 23:54

активно использую формат blueprint, всё, что описано в статье для RAML есть и в блупринте. Результат получается красивый и для пользователя удобный, но вот для писателя формат api blueprint немного корявенький, очень неудобно, например, следовать через чур строгим требованиям по количеству пробелов и табуляций: список параметров — значит два таба, ещё что-то — четыре таба и т.д. Это кажется немного излишним, ведь распарсить явно и так всё получится.

mnv Aug 25 2015 at 00:08

У нас на PHP проекте API описано на WSDL, это описание работает и для первичной валидации. Документацию получаем с помощью XSLT преобразования WSDL-ки. Подход хорошо себя зарекомендовал. Но приведенный в статье набор инструментов вокруг RAML впечатляет.

lair Aug 25 2015 at 00:43

А у вас REST API или SOAP API?

mnv Aug 25 2015 at 00:57

Именно REST

lair Aug 25 2015 at 01:05

А как вы в wsdl описали rest-ресурсы и, особенно, http-семантику?

mnv Aug 25 2015 at 09:10

Пример, входные параметры:

 <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>

lair Aug 25 2015 at 10:00

Это ваше собственное расширение или какой-то публичный фреймворк?

mnv Aug 25 2015 at 10:27

Фрейморк-то Yii2, но он тут ни при чем. Работа с WSDL через \DOMDocument.

lair Aug 25 2015 at 10:29

Ну то есть ваше собственное расширение.

mnv Aug 25 2015 at 10:30

Методы для работы с \DOMDocument, кстати, вынесены в отдельную библиотеку, или скорее даже фреймворк, его у нас соседняя команда сделала, но он к сожалению не публичный.

lair Aug 25 2015 at 11:06

Мне достаточно того, что это ваше расширение, со всеми (отсутствующими) перспективами стандартизации и широкого распространения.

(btw, на глаз в нем есть ощутимое количество ошибок и неполноты, но, поскольку он ваш внутренний, это не принципиально)

AndreiYemelianov Aug 25 2015 at 10:45

Слишком сложно…

Кстати, а существуют ли какие-нибудь генераторы интерактивной документации для WSDL?

lair Aug 25 2015 at 11:06

Не знаю про интеграктивную документацию, а вот клиенты на основании wsdl строятся, в том числе и песочницы.

mnv Aug 25 2015 at 11:11

Не сказал бы, что слишком сложно. По сути, за валидацию отвечает несколько строк. Если упрощенно, то примерно так:

$validator = new \DOMDocument( '1.0', 'UTF-8' );
$validator->loadXML( $xml );
if (!$validator->schemaValidateSource($xsd)) {
  ...
}

Т.е. в PHP для этого готовые инструменты есть.
Или громоздко описания выглядят? Ну, возможно. Меня не напрягает, думаю, дело привычки.
Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.

lair Aug 25 2015 at 11:23

А если у вас данные не в xml гуляют?

mnv Aug 25 2015 at 12:10

Бывает и такое. В этом случае просто JSON преобразуем в XML и направляем на валидацию

lair Aug 25 2015 at 12:12

И вас не смущает, что вы в этом случае требуете, чтобы JSON имел конкретную последовательность элементов, чего он гарантировать не может и не будет?

(ну и вообще это не вполне однозначное преобразование, если вы только не накладываете на xml и xsd дополнительных ограничений)

mnv Aug 25 2015 at 13:29

Не смущает, на этот случай был придуман велосипед — переданные параметры сортируются в алфавитном порядке. В WSDL тоже параметры описаны в алфавитном порядке. Но, как оказалось, на этот случай есть готовое простое решение — вместо sequence можно использовать all в WSDL.
Некоторые ограничения на формат есть, но по практике скажу, что трудностей это не создает.

AndreiYemelianov Aug 25 2015 at 12:24

Да, сами описания выглядят несколько громоздко, что немного напрягает.

>>>Автоматические генераторы есть, и тут уже больше философский вопрос, что первично — документация или код. Мне близок подход, когда сперва составляется осмысленная документация.>>>>

Я ничего не имею против этого подхода. Задавая свой вопрос, я никаких философских аспектов затрагивать не хотел. Мне действительно интересно, насколько сейчас распространён WSDL, как он поддерживается сообществом, какие есть вспомогательные инструменты.

AndreiYemelianov Aug 25 2015 at 09:44

Присоединяюсь к вопросу.

ArthurKushman Jan 10 2017 at 14:25

Привет бывшему коллеге, все верно — в тот период, когда 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.

ArthurKushman Jan 10 2017 at 14:42

Ой, простите ссылку забыл выделить, а комент не могу отредактировать — https://github.com/RJAPI/raml-json-api

roces Aug 25 2015 at 01:29

Вообще RAML спецификация как и инструменты для работы с ним, мягко говоря, не особо обновляются в последнее время (около года).
Его удобно использовать, чтобы быстро спроектировать REST API и окинуть взглядом как все вместе выглядит.

Из того что не хватает в версии 0.8:
1. Поддержка массивов: some_path/1,2,3,5.json Никак это нельзя описать, только если отдельное описание вставлять.
2. Поддерживает только '=' в query string. Т.е. нельзя описать что-то типа: path?star<2015-08-27T08:30:00.000Z