RAML (RESTful API Modeling Language) используется для проектирования и документирования веб-сервисов REST. Официальный сайт: https://raml.org.
Легче всего редактировать файлы RAML в api-workbench. Для этого сначала установите текстовый редактор Atom, а затем в консоли наберите команду:
|
1 |
apm install api-workbench |
Запустите текстовый редактор Atom. Установленный API Workbench должен появиться в Packages:
Файл RAML на самом деле является обычным файлом YAML, но с расширением “*.raml”, например “myservice.raml”. В начале идёт заголовок:
|
1 2 3 4 |
#%RAML 1.0 title: myservice version: v1 baseUri: http://api.samplehost.com |
В первой строке мы указываем версию формата RAML. В title указывается название описываемого сервиса. В version мы указываем версию API. В baseUri указывается адрес, куда задеплоен сервис.
Затем мы описываем составные типы данных, которые используются в нашем API:
|
1 2 3 4 5 6 7 8 9 10 |
types: TestType: type: object properties: id: number optional?: string expanded: type: object properties: count: number |
Мы описали тип TestType со свойствами id, optional и expanded. Обратите внимание на знак вопроса после optional. Знак вопроса в конце имени свойства означает, что это свойство необязательное. Свойство expanded само является объектом, содержащим другие свойства внутри себя.
При описании объектов мы как правило заполняем следующее:
- type? — базовый тип, который мы расширяем нашим типом;
- description? — человекопонятное описание типа;
- displayName? — человекопонятное имя типа;
- example? — пример использования.
Например:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
types: Monster: type: object description: Just monster base displayName: Monster base type properties: health:number ammo?:number name:string example: health:100 ammo: 10 name:BaseMonster Daemon: type: Monster displayName: Daemon properties: energy: number example: health:100 ammo:10 name:Sticky Daemon energy: 999 |
При описании свойств мы использовали number и string. В RAML существуют следующие типы данных:
- string — строки;
- number — числа;
- integer — целые числа;
- boolean — логические true и false;
- date-only — только дата в формате yyyy-mm-dd;
- time-only — только время в формате hh:mm:ss[.ff…];
- datetime-only — дата и время в формате yyyy-mm-ddThh:mm:ss[.ff…]
- datetime — дата и время с часовым поясом (пример: 2016-02-28T16:41:41.090Z);
- file — файл в BASE64;
- nil — nil.
После описания типов идёт описание самих вызовов сервисов:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
/myservice: get: responses: 200: body: application/json: example: | { "message" : "Hello World" } /monsters: get: responses: 200: body: application/json: description: Monsters list type: array items: Monster example: [{ health: 99 name: monster1 }] 204: post: description: Create a monster body: application/json: type: Monster example: { health: 50 name: Vasya } responses: 200: |
Здесь мы описали следующие возможные вызовы:
Возвращает Hello World:
GET /myservice/
Возвращает массив монстров:
GET /myservice/monsters
Используется длс создания монстра:
POST /myservice/monsters
Я даже не знаю, стоит ли тут что-то описывать. После url мы указываем тип HTTP запроса (get, post и т. д.). В responses указываются возможные HTTP коды ответов сервера, а в body описываем сам ответ.
Например GET /myservice/monsters будет возвращать JSON с массивом элементов типа Monster, либо HTTP код 204 No Content.
POST запрос на /myservice/monsters возвращает пустое тело и HTTP статус 200. А в качестве параметра ожидает application/json с одним элементом Monster.
В отличие от Swagger, который генерирует документацию по аннотациям сервисов, RAML нацелен на то, что клиентский и серверный код будут генерироваться по файлу RAML. На официальном сайте указаны ссылки на генераторы кодов для PHP, Rube, Java и других языков.
Swagger так же позволяет сгенерировать сервер на основе yml конфига, причем для этого не обязательно скачивать и/или устанавливать доп. ПО. Весь функционал доступен на их сайте