О 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’acces automatise 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, приглашаем поделиться опытом. Если вам кажется, что мы забыли рассказать о каком-то интересном нововведении — напишите нам, и мы обязательно добавим его в обзор.

Если вы по тем или иным причинам не можете оставлять комментарии здесь — добро пожаловать в наш корпоративный блог.