RAML 1.0: огляд нововведень

RAML 1.0

Про RAML   мовою розмітки, що використовується для опису RESTful API, ми  писали. У обговорення статті на Хабрахабре один з читачів зауважив, що RAML вже давно не оновлюється, трохи не з літа 2014 року.

Кілька місяців формат RAML був суттєво вдосконалений. Нова специфікація версії 1.0 була опублікована на офіційному сайті відносно недавно, в початку жовтня 2015 року. &Nbsp;порівняно з попередньою версією (0.8) неї було внесено багато змін і доповнень. Про найбільш значних нововведень ми докладно розповімо в цієї статті.


Типи даних

Найважливіша новація в RAML 1.0 — це підтримка типів даних. Тепер у вступній частині документа можна дуже детально описувати всі типи даних, з якими працює API:

#%RAML 1.0 
title: New API
mediaType: application/json
types: 
Person:
type: object #
властивості:
firstname: string
lastname: string
is_our_employee: boolean
Document: 
type: object
properties: Author
title: string
signing_date: date


Типи даних, визначені специфікації, можна використовувати в надалі при описі тел відповідей, параметрів URI, заголовків і query-парамертров, наприклад:

/documents/{documentId}:
get:
responses:
200:
body:
application/json:
type: Document


Приклади: розширені можливості

У документації до будь API бажано наводити якомога більше прикладів.
У RAML 1.0 приклади можна додавати в яку частину документа. Приклади можуть представлені як в форматі JSON, так і YAML:

#%RAML 1.0 
title: New API
mediaType: application/json
types: 
Person:
type: object #
властивості:
firstname: string
lastname: string
is_our_employee: boolean
examples:
{
firstname: Alexander
lastname: Ivanov
is_our_employee: true
}


Завдяки прикладам опис API стає більш зрозумілим і наочним.

Анотації

З допомогою анотацій специфікації RAML можна вставляти додаткові метадані. Ця можливість корисна при проектуванні API: анотації можна додати інформацію, яка виявиться корисною в надалі (для тестування, доповнення документації та тощо).
Розглянемо простий приклад (взято з офіційній документації):

#%RAML 1.0
title: Illustrating annotations
mediaType: application/json
annotationTypes:
experimental:
/groups:
(experimental):


У вступній частині документа (атрибут annotationTypes) описується загальний формат анотацій. Далі один з эндпоинтов API позначений як експериментальний.

Анотації можна використовувати і в більш складних ситуаціях   наприклад, для опису тест-кейсів:

#%RAML 1.0 
title: Testing annotations
mediaType: application/json
annotationTypes:
testCase:
allowedTargets: [ Method ]
allowMultiple: true
usage: |
Use this annotation to declare a test case.
You may apply this annotation multiple times per location.
властивості:
scenario: string
setupScript?: string[]
testScript: string[]
expectedOutput?: string
/documents:
type: myResourceTypes.collection
get:
(testCase):
scenario: No Documents
setupScript: deleteAllDocuments
testScript: getAllDocuments
expectedOutput: [ ]
(testCase):
scenario: Document One
setupScript: [ deleteAllDocuments, addDocs ]
testScript: getAllDocuments
expectedOutput: '[ { "id": 999, "author": "John Smith" } ]'
(testCase):
scenario: Multiple Documents
setupScript: [ deleteAllDocuments, addDocs ]
testScript: getAllDocuments
expectedOutput: '[ { "id": 998, "author": "Bob Brown" }, { "id": 999, "name": "John Smith" } ]'


Бібліотеки

Ще одне нововведення RAML 1.0   бібліотеки. Бібліотекою називається файл, який винесені профілі, типи даних і інша інформація, що поміщається під вступну частину документа. Тепер у новому документі можна не розписувати докладно вступну частину, а послатися на вже наявні бібліотеки. Така практика нагадує підключення зовнішніх бібліотек і модулів у програмному коді.
Наведемо приклад бібліотеки:

#%RAML Library 1.0
# Цей файл зберігається в libraries/files.raml 
usage: |
Use to define some basic file-related constructs.
types:
File:
властивості:
name:
type: string
length:
type: integer
traits:
drm:
headers:
drm-key:
resourceTypes:
file:
get:
is: drm
put:
is: drm


Після того, як бібліотека збережена в окремому файлі, до ній можна звертатися в основному файлі специфікації:

#%RAML 1.0 
title: Files API
uses:
files: !include libraries/files.raml
resourceTypes:
file: !include files-resource.raml
/files:
type: file


Надбудови і розширення

Надбудови (фоліо) і розширення (extensions) призначені для кастомізації описів API — наприклад, коли потрібно створити (і потім регулярно оновлювати і підтримувати) документацію до API на кількох мовах. Задача ця не так проста, як може здатися на перший погляд. Більшість наявних інструментів для документування API не можуть впоратися з цим завданням без додаткових «милиць».

У RAML 1.0 з допомогою надбудов можна без проблем реалізувати підтримку багатомовною документації. Уявімо, що у нас є документація до API на англійською мовою, і нам потрібно зробити для неї французьку локалізацію. Англійська документація зберігається в файлі booklibrary.raml. Наведемо невеликий фрагмент:

#%RAML 1.0

title: Book Library API
documentation: 
- title: Introduction
content: automated access to the books
- title: Licensing
content: Please respect the copyright on this book


Щоб додати французьку локалізацію, створимо файл-надбудову (overlay):

#%RAML 1.0 Overlay
usage: French localisation
masterRef: booklibrary.raml
documentation: 
- title: Introduction
content: l accès automatisé aux livres
- title: licenсe
content: Respectez les droits d auteur s.v.p.


Цей файл містить тільки французькі переклади; всі описи методів і відповідей при генерації будуть взяті з основного файлу.

C допомогою розширень (extensions) можна створювати додаткові опису методів і відповідей. Це може знадобитися для адаптації опису API для різних категорій користувачів або для різних варіантів використання (наприклад, в ситуації, коли користувачам безкоштовної версії сервісу доступний базовий, а користувачам платної версії   розширений набір функцій),

Розглянемо наступні фрагменти (приклади взяті звідси):

Основний файл


#%RAML 1.0
title: Book Library API
documentation:
- title: Introduction
content: Automated access to books
- title: Licensing
content: Please respect copyrights on our books.
/books:
description: The collection of library books
get:


Розширення з описом функціональності API для користувачів з правами адміністратора


#%RAML 1.0 Extension
usage: Add administrative functionality
masterRef: librarybooks.raml
/books:
post:
опис: Add a new book to the collection


Розширення для кастомних версії API, доступною за вказаним URL


#%RAML 1.0 Extension
usage: The location of the public instance of the Piedmont library API
masterRef: librarybooks.raml
baseUri: http://api.piedmont-library.com


Висновок

Розглянуті нами нововведення свідчать про те, що RAML розвивається в бік простого, але   же час дуже гнучкого мови опису, що дозволяє документувати навіть найскладніші API.

Радує і те, що зараз з'являються і нові, більш досконалі інструменти для створення документації для API. Восени 2015 року компанія MuleSoft (основний розробник RAML) випустила плагін API WorkBench (див. також репозиторій на GitHub для текстового редактора Atom   рекомендуємо звернемо увагу. Будемо сподіватися, що надалі цей інструмент буде успішно розвиватися.

Якщо ви вже користувалися RAML 1.0 для документування API, запрошуємо поділитися досвідом. Якщо вам здається, що ми забули розповісти про якомусь цікавому нововведення   напишіть нам, і  обов'язково додамо його в огляд.

Якщо ви з тих чи інших причин не можете залишати коментарі тут — ласкаво просимо в наш корпоративний блог.

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.