Удобство работы с любым API во многом зависит от качества его документации. Стандартизация и унификация описания API актуальны, и выбор подходящего формата для документирования – важная задача. Выбор пал на RAML.
Что такое RAML?
RAML (RESTful API Modeling Language) – специализированный язык для описания REST API. Незнание REST API требует ознакомления с соответствующими материалами.
Альтернативные подходы и их недостатки
Простой текстовый документ – первый вариант, который приходит в голову. Однако такой подход имеет ряд недостатков: сложность поддержания актуальности, недостаточная наглядность и ограниченная область применения (например, невозможность сгенерировать интерактивную тестовую страницу).
Специализированные инструменты и сервисы, генерирующие документацию на основе JSON или Markdown, также имеют проблемы. JSON, изначально предназначенный для обмена данными, требует использования «костылей», например, кастомных полей. Ручное создание описаний в JSON – трудоемкий процесс, особенно для больших API.
Аналогичные трудности испытывают пользователи Swagger, где для упрощения работы создан фирменный редактор с поддержкой YAML. Хотя YAML удобнее JSON, в нём отсутствует возможность однократного описания повторяющихся элементов (например, схемы ответа) для повторного использования.
Markdown, используемый в API Blueprint, предназначен для форматирования текста, а не для генерации документации API, поэтому его адаптация сложна. Попытки на базе XML (например, WADL) также не получили широкого распространения.
RAML разработан специально для описания API, исправляя недостатки других форматов. Первая версия спецификации была опубликована в 2013 году компанией MuleSoft при участии Cisco, PayPal, Box Inc. и других.
Преимущества RAML
Основные преимущества RAML:
- Простота и логичность синтаксиса: основан на YAML.
- Поддержка наследования: позволяет использовать уже описанные элементы.
- Подключение внешних файлов: ускоряет разработку и снижает дублирование кода.
- Большое количество конвертеров, парсеров и генераторов: позволяет создавать различные виды документации.
Структура документа RAML
Файл спецификации RAML состоит из следующих элементов:
- Вводная часть (шапка): включает версию RAML, имя документа, URI API и версию API. Может содержать дополнительную информацию, например, сведения о протоколе и метаданные.
- Схема безопасности (Security Schemes): описывает методы авторизации (OAuth 2.0, HTTP-аутентификация и др.). Примеры могут храниться в отдельных YAML или RAML файлах.
- Описание ресурсов (Resources): описывает основные ресурсы API, пути к ним и используемые HTTP-методы (GET, PUT, POST, DELETE). Включает описание HTTP-заголовков (с указанием обязательности – required: true/false). Используются дополнительные параметры, такие как type, description, pattern (регулярные выражения).
- Профили (Traits): позволяют избежать повторений в описаниях, прописываются во вводной части и используются при описании методов.
- Описание ответов: включает код ответа, схему (перечисление параметров и типов) и пример ответа. Схемы ответов можно хранить в отдельных файлах.
Инструменты для работы с RAML
Для RAML разработано множество конвертеров и парсеров. Например, raml2html генерирует статическую HTML-страницу (установка через npm). Существуют также raml2wiki и конвертеры для Swagger.
- API Designer (MuleSoft): онлайн-инструмент для написания документации и тестирования API. Предоставляет интерактивный редактор, платформу для тестирования и хранит статистику тестовых запросов. Поддерживает загрузку RAML-файлов и импорт спецификаций Swagger.
- API Console (MuleSoft): инструмент для генерации документации в браузере. Поддерживает загрузку файлов с локальной машины и внешних источников. Включает примеры описаний API популярных веб-сервисов. Генерируемая документация интерактивна и позволяет выполнять тестовые запросы.
RAML – простой и логичный язык для документирования REST API. Его преимущества – простота, логичность синтаксиса и наличие множества инструментов для работы. Ожидается более широкое распространение RAML в будущем.