RAML 1.0: обзор нововведений

О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.

Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.

Типы данных

Самая важная новация в RAML 1.0 — это поддержка типов данных. Теперь во вводной части документа можно очень подробно описывать все типы данных, с которыми работает API:

#%RAML 1.0
title: New API
mediaType: application/json
types:
  Person:
    type: object #
    properties:
      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 #
    properties:
      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.
    properties:
      scenario: string
      setupScript?: string[]
      testScript: string[]
      expectedOutput?: string
/documents:
  type: myResourceTypes.collection
  get:
    (testCase):
      scenario: No Documents
      setupScript: deleteAllDocuments
      testScript: getAllDocuments
      expectedOutput: [ ]
    (testCase):
      scenario: One Document
      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 1.0 Library
# Этот файл хранится в libraries/files.raml
usage: |
  Use to define some basic file-related constructs.
types:
  File:
    properties:
      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

Надстройки и расширения

Надстройки (overlays) и расширения (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:
    description: 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, приглашаем поделиться опытом. Если вам кажется, что мы забыли рассказать о каком-то интересном нововведении — напишите нам, и мы обязательно добавим его в обзор.

Что еще почитать по теме

T-Rex 30 марта 2021

Что такое SMTP-протокол и как он устроен?

SMTP (Simple Mail Transfer Protocol) — протокол передачи почты. Он был представлен еще в 1982 году, но не теряет актуальности до сих пор. В статье разбираемся, какие задачи решает протокол и как он ра…
T-Rex 30 марта 2021
Владимир Туров 1 сентября 2020

Дело совершенно секретного iPod

Это был обычный серый день в конце 2005 года. Я сидел на рабочем месте и писал код для следующей версии iPod. Вдруг без стука ворвался директор ПО для iPod, начальник моего начальника, и закрыл дверь.
Владимир Туров 1 сентября 2020
T-Rex 21 августа 2020

TrendForce: цены на SSD упадут

Эксперты DRAMeXchange предсказывают значительное падение цен на оперативную память и твердотельные накопители в ближайшее время. Причина — сокращение спроса на чипы для NAND и DRAM.
T-Rex 21 августа 2020

Новое в блоге

Михаил Фомин 24 июня 2022

Docker Swarm VS Kubernetes — как бизнес выбирает оркестраторы

Рассказываем, для каких задач бизнесу больше подойдет Docker Swarm, а когда следует выбрать Kubernetes.
Михаил Фомин 24 июня 2022
Ульяна Малышева 30 сентября 2022

«Нулевой» локальный диск. Как мы запустили облако только с сетевыми дисками и приручили Ceph

Чем хороши сетевые диски и почему именно Ceph, рассказал директор по развитию ядра облачной платформы Иван Романько.
Ульяна Малышева 30 сентября 2022
Валентин Тимофеев 30 сентября 2022

Как проходит онбординг сотрудников ИТО? Что нужно, чтобы выйти на смену в дата-центр

Рассказываем, как обучаем новых сотрудников, какие задачи и испытания проходят инженеры прежде, чем выйти на свою первую смену.
Валентин Тимофеев 30 сентября 2022
T-Rex 28 сентября 2022

Книги по SQL: что почитать новичкам и специалистам

Собрали 6 книг, которые помогут на старте изучения SQL и при углублении в тему.
T-Rex 28 сентября 2022