Введение в RAML

RAML (RESTful API Modeling Language) используется для проектирования и документирования веб-сервисов REST. Официальный сайт: https://raml.org.

Легче всего редактировать файлы RAML в api-workbench. Для этого сначала установите текстовый редактор Atom, а затем в консоли наберите команду:

Запустите текстовый редактор Atom. Установленный API Workbench должен появиться в Packages:

Atom / Packages/ API Workbench / Create RAML Project
Create RAML Project

Файл RAML на самом деле является обычным файлом YAML, но с расширением “*.raml”, например “myservice.raml”. В начале идёт заголовок:

В первой строке мы указываем версию формата RAML. В title указывается название описываемого сервиса. В version мы указываем версию API. В baseUri указывается адрес, куда задеплоен сервис.

Затем мы описываем составные типы данных, которые используются в нашем API:

Мы описали тип TestType со свойствами id, optional и expanded. Обратите внимание на знак вопроса после optional. Знак вопроса в конце имени свойства означает, что это свойство необязательное. Свойство expanded само является объектом, содержащим другие свойства внутри себя.

При описании объектов мы как правило заполняем следующее:

  • type? — базовый тип, который мы расширяем нашим типом;
  • description? — человекопонятное описание типа;
  • displayName? — человекопонятное имя типа;
  • example? — пример использования.

Например:

При описании свойств мы использовали 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.

После описания типов идёт описание самих вызовов сервисов:

Здесь мы описали следующие возможные вызовы:

Возвращает 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 и других языков.

Один комментарий к “Введение в RAML”

  1. Swagger так же позволяет сгенерировать сервер на основе yml конфига, причем для этого не обязательно скачивать и/или устанавливать доп. ПО. Весь функционал доступен на их сайте

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *