- 24.08.15 11:51 •
- yuhenobi •
- # 265337 •
- Хабрахабр •
- 37 •
- 8709
- такий же як Forbes, тільки краще.
Зручність роботи з будь-яким API багато в чому залежить від того, як написана і оформлена його документація. Cейчас ми ведемо роботу по стандартизації і уніфікації опису всіх наших API, і питання документування для нас особливо актуальні.
Після довгих пошуків ми вирішили оформляти документацію в форматі RAML. Так називається спеціалізований мова для опису REST API. Про його можливості та переваги ми розповімо в цій статті.
чому RAML
Як потрібно документувати API? Питання це не таке просте, як може здатися на перший погляд.
Перший і найпростіший варіант, який приходить на розум - представити опис до API у вигляді звичайного текстового документа. Так роблять дуже багато (в тому числі і дуже відомі компанії). Ми теж не раз користувалися цим способом. При всій своїй простоті він має наступні недоліки:
- текстову документацію складно підтримувати в актуальному стані;
- найчастіше словесні описи API виявляються недостатньо наочними;
- сфера використання «словесної» документації дуже обмежена (наприклад, на її основі можна згенерувати інтерактивну тестову сторінку).
Щоб спростити процес документування, можна використовувати спеціалізовані інструменти та сервіси. Як правило, вони генерують документацію на основі опису в деякому стандартизованому форматі - зазвичай це JSON або Markdown.
Жоден з цих форматів для написання документації не підходить. JSОN був спочатку створений для обміну даними в Інтернеті. При використанні його для інших цілей мимоволі доводиться вдаватися до допомоги «милиць» - наприклад, кастомних полів, що починаються зі знака $. Крім того, складати описи в форматі JSON вручну - справа досить рутинне і обтяжлива (особливо якщо мова йде про описи великого розміру).
Звичайно, YAML набагато зручніше, ніж JSON. Але і його використання пов'язане з певними труднощами. Справа в тому, що в описах API завжди є елементи, що повторюються (наприклад, схема відповіді, яка може бути однаковою для різних типів HTTP-запитів), які доводиться всякий раз прописувати вручну. От якби можна їх було раз і назавжди прописати в окремому файлі і посилатися на нього в разі небходимости ... Але, на жаль, поки що такої можливості немає.
Безперечними перевагами RAML є:- простий і логічний синтаксис, заснований на форматі YAML;
- підтримка успадкування і можливість підключення зовнішніх файлів специфікацій.
Додатковим плюсом є наявність великої кількості конвертерів, парсеров і генераторів інтерактивної документації. Про деякі з них ми розповімо нижче, а поки перейдемо до огляду особливостей синтаксису RAML.
Короткий вступ в RAML
структура документа
Файл специфікацій на RAML складається з наступних структурних елементів:
- вступна частина ( «шапка»);
- схема безпеки;
- опис профілів;
- опис об'єктів і методів;
- опис відповідей.
Розглянемо ці елементи докладніше.
Вступна частина
Кожен документ на RAML починається з вступної частини, яка включає чотири обов'язкові елементи:
- версія RAML;
- ім'я документа;
- URI, за яким доступний API;
- версія API, що описується в документації.
Виглядає це так:
Вступна частина може також включати різну додаткову інформацію - наприклад, відомості про використаний протоколі для зв'язку з API:
Можна у вступній частині прописати і метадані файлу документації:
схеми безпеки
Наведений фрагмент містить наступну інформацію:
Це допомагає прискорити процес документування, уникнути зайвих повторень і зробити документацію менш громіздкою.
Почитати докладніше про схемах безпеки і ознайомитися з конкретними прикладами можна тут (розділ Security).
Об'єкти і методи
Далі перераховуються основні об'єкти та шляхи до них, а також HTTP-методи, які використовуються з цими об'єктами:
У наведеному прикладі описується API, за допомогою якого можна працювати з документами. Ми можемо завантажувати документи на локальну машину (GET), змінювати Існуючі документи (PUT) і завантажувати нові (POST). З кожним окремим документом () ми можемо також виконувати такі операції: завантаження на локальну машину (GET) і видалення (DELETE).
HTTP-заголовки, використовувані з тим чи іншим методом, описуються за допомогою властивості headers, наприклад:
Зверніть увагу на властивість required: воно вказує, чи є заголовок обов'язковим (true) або необов'язковим (false).
В описі об'єктів і методів можуть використовуватися численні додаткові параметри. Розглянемо наступний приклад:
Тут ми вказуємо, що кожен з документів, доступ до яких можна отримати через API, має власний ідентифікаційний код у вигляді рядка (type: string), а також описуємо формат цього коду за допомогою регулярних виразів.
Властивості description, type та pattern можна використовувати і в описах методів, наприклад:
Для кожного методу можна прописати індивідуальну схему безпеки:
Query-параметри
Для кожного методу в документації можна вказати query-параметри, які будуть використовуватися в запиті. Для кожного query-параметра вказуються такі характеристики: ім'я, тип, опис і приклад:
Щоб уникнути зайвих повторень в описах, в RAML використовуються профілі (traits), які прописуються у вступній частині документа:
Надалі до профілю можна звертатися при описі будь-яких методів:
Більш докладно про профілі і особливості їх використання можна почитати в офіційній документації (розділ Traits).
опис відповіді
В описі відповіді обов'язково вказується його код. Також в опис можна додати схему (schema) - перерахування входять у відповідь параметрів і їх типів. Можна також навести приклад конкретної відповіді (example).
Схема відповідей можна зберігати в окремих файлах формату .yml або .raml і звертатися до них в інших частинах документації:
Візуалізація і генерація документації
RAML2HTML і інші конвертери
Незважаючи на те, що RAML - формат відносно новий, для нього вже розроблена достатня кількість конвертерів і парсеров. Як приклад можна привести ram2htmtl. генерує на основі опису в форматі RAML статичну HTML-сторінку.
Встановлюється він за допомогою менеджера пакетів npm:
Щоб конвертувати RAML-файл в HTML, досить виконати просту команду:
API Designer
У правій частині сторінки автоматично генерується інтерактивна документація. Тут же можна і протестувати API: для цього досить просто розгорнути опис потрібного запиту і натиснути на кнопку Try it.
API Designer дозволяє також завантажувати RAML-файли з локальної машини. Підтримується імпорт файлів описів API для Swagger.
Крім того, API Designer зберігає статистику тестовиx запитів до API.
API console
API console - корисний інструмент, розроблений все тієї ж компанією MuleSoft. З його допомогою можна прямо в браузері генерувати документацію до API. Файли специфікацій можна як завантажити з локальної машини, так і вказати посилання на зовнішнє джерело:
До складу API Console входить кілька файлів-зразків, що представляють собою опису API популярних веб-сервісів: Twitter, Instagram, Box.Com, LinkedIn. Ми спробували згенерувати на основі одного з низ документацію - виглядає цілком симпатично:
Документація, що отримується на виході, є інтерактивною: в ній можна не тільки прочитати опис API, але і виконати тестові запити.
висновок
Тільки зареєстровані користувачі можуть брати участь в опитуванні. Увійдіть. будь ласка.
Чим краще? Відповідаю по пунктах?
1. Набагато більш простим і логічним синтаксисом описів.
2. Можливістю розписати в документації набагато більшу кількість параметрів, ніж в тому ж swagger і, найголовніше, зробити це за допомогою більш простих і зручних конструкцій (порівняйте ті ж описи схем безпеки або query-параметрів).
3. Розширеними (в порівнянні з тим же swagger) можливостями використання include'ов і успадкування, завдяки чому документація виходить більш компактною та елегантною.
Єдине, в чому RAML поки що програє Swagger - недостатня кількість розроблюваних спільнотою інструментів. Але це - справа наживна.
Для RAML є інструменти, що дозволяють автоматично генерувати документацію в цьому форматі для вже існуючого API (бажано - на льоту)?
активно використовую формат blueprint, все, що описано в статті для RAML є і в блупрінте. Результат виходить красивий і для користувача зручний, але ось для письменника формат api blueprint трохи корявенько, дуже незручно, наприклад, слідувати через чур суворим вимогам по кількості прогалин і табуляцій: список параметрів - значить два таба, ще щось - чотири таба і т . Д. Це здається трохи зайвим, адже розпарсити явно і так все вийде.
У нас на PHP проект API описано на WSDL, це опис працює і для первинної валідації. Документацію отримуємо за допомогою XSLT перетворення WSDL-ки. Підхід добре себе зарекомендував. Але наведений у статті набір інструментів навколо RAML вражає.