Каталог решений - Приемы описания документации API используя нотацию RAML

Приемы описания документации API используя нотацию RAML

Приемы описания документации 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" (документация)

 

has been added to your cart:
Оформление заказа