Приемы описания документации API используя нотацию RAML
В статье опишу приемы, которые использую в своей работе, и которые позволяют быстро реализовать описание.
- Описание
- Подробнее
Описание
Вводные
Нужно описать документацию на HTTP API, опубликовать в понятном заказчику и исполнителю виде.
Реализация
Для описания использую нотацию RAML (https://raml.org/), в результате получаю набор текстовых файлов которые удобно версионизировать в git. Для публикации использую формат HTML, .raml конвертирую в .hrml c помощью утилиты raml2html (https://github.com/raml2html/raml2html). С исходным текстом работаю используя Atom (https://atom.io/) и плагин API Workbench (https://atom.io/packages/api-workbench), в нем нормально работает автодополнение.
В средах разработки используется монофайл описания, что для меня не удобно (Обсуждение вопроса), проект из нескольких файлов можно собрать в один с помощью oas-raml-converter-cli (Ссылка на статью) более современный вариант webapi-parser (https://github.com/raml-org/webapi-parser).
Структура проекта
1. файл api.raml — корневой файл описания
2. папка dataTypes с описанием типов данных
3. папка resourceTypes с описанием типов ресурсов
4. папка securitySchemes — с схемами безопасности
Корневой файл
Обычно работаю с JSON форматом, поэтому в шапке описываю "mediaType: application/json", чтобы после в каждом ресурсе не уточнять.
Для всего API устанавливаю схему безопасности через "securedBy: token" (документация)