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

24.06.20

Интеграция - WEB-интеграция

В статье опишу приемы, которые использую в своей работе, и которые позволяют быстро реализовать описание.

Вводные

Нужно описать документацию на 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" (документация)

 
 Шапка api.raml

 

Ресурс по работе со справочниками описываю так:

 
 Ресурс product

Далее опишу из чего он компонуется и как на выходе получается CRUD описание

 

Типы данных

Все типы данных (схемы данных) организую в виде библиотеки и подключаю её в корневой файл

 
 Библиотека /dataTypes/library.raml
 
 Описание типа dataTypes/ProductType.raml

По умолчанию все реквизиты объектов "required: true", что отражается в публикации документации.

 

Если используются guid то добавляю тип, чтобы регулярные выражения заработали через параметр "pattern" не получилось, поэтому разместил в описании.

 
 Тип GUID

При размещении типа в корневом файле в файлах типов данных он может использоваться так:

 
 ProductType c parent тип GUID

 

При работе с объектом по API отправляю данные без идентификатора, получаю ответ с ним, для решения описания вопроса использую наследование объектов, добавляя нужные реквизиты к базовому типу

 
 Описание типа dataTypes/ProductResponseType.raml

 

Примеры типов данных

Обычно при разработке программисты запрашивают примеры. Их можно добавить в описание к типу, при публикации тип будет 

 
 Описание типа остатков
 
 Описание типа табличной части остатков
 
 Пример типа остатков

 

Типы ресурсов

Стандартный набор операций включает

  1. получение списка элементов, GET /
  2. получение элемента GET /{id}
  3. добавление элемента POST
  4. обновление элемента PUT /{id}
  5. удаление элемента DELETE /{id}

Описывать весь набор для каждого типа данных неудобно поэтому использую описание типов ресурсов (документация)

Использую описание для коллекции

 
 /resourceTypes/collection-item.type.raml

и для элемента

 
 /resourceTypes/item.type.raml

Подключаю в корневом файле

 
 подключение в api.raml

 

При ошибке поиска выдаю ответ 406, чтобы он не пересекался с 404, который может выдать сервер перед API и будет ложное срабатывание при схеме

Если GET /{id}=200 Тогда PUT /{id} Иначе POST / 

Формат ответа об ошибке один и тот же поэтому использую для этого отдельный тип

 
 /dataTypes/ResponseType.raml

 

Для использования имени url для получения типа данных использую "<<resourcePathName" (документация)

В результате состыковки будет подключен тип

properties:
   result:
   type: array
   items: DataLib.productResponse

 

Особенности

Для некоторых ресурсов нужна пагинация или фильтрация, её можно организовать в traits (особенности) (документация)

 
 Особенность фильтрации и пагинаци

и подключить её в ресурсе

get:
    is:  [filtered]

 

Итог

В результате компоновки инструментов можно быстро и качественно писать документацию на HTTP API и опубликовать

 
 Внешний вид опубликованного API
 
 Внешний вид описания ресурса

 

Благодарю за внимание.

RAML API

См. также

Интеграция Альфа Авто 5 / Альфа Авто 6 и AUTOCRM / Инфотек

Сайты и интернет-магазины WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 1С:Управление торговлей 11 Автомобили, автосервисы Россия Управленческий учет Платные (руб)

Интеграционный модуль обмена между конфигурацией Альфа Авто 5 и Альфа Авто 6 и порталом AUTOCRM. Данный модуль универсален. Позволяет работать с несколькими обменами AUTOCRM разных брендов в одной информационной базе в ручном и автоматическом режиме.

36000 руб.

03.08.2020    15748    10    17    

11

Интеграция 1С — Битрикс24. Обмен задачами

Сайты и интернет-магазины Интеграция WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 Управленческий учет Платные (руб)

Интеграция 1С и Битрикс24. Разработка имеет двухстороннюю синхронизацию 1С и Битрикс24 задачами. Решение позволяет создавать пользователя в 1С из Битрикс24 и наоборот. Данная разработка технически подходит под все основные конфигурации линейки продуктов 1С:Предприятие 8.3 (8.3.18.1289). При приобретении предоставляется 1 месяц бесплатных обновлений разработки. Доступна демо-версия продукта с подключением Вашего Битрикс24

5040 руб.

04.05.2021    17551    6    15    

13

Интеграция с сервисом vetmanager

WEB-интеграция Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бытовые услуги, сервис Платные (руб)

Внешняя обработка разрабатывалась для загрузки документов из Ветменеджер в 1С: Бухгалтерия 3.0

12000 руб.

02.02.2021    16360    42    49    

23

[Расширение] БОР-Навигатор.Культура

Зарплата Бюджетный учет WEB-интеграция Обмен с ГосИС Платформа 1С v8.3 Сложные периодические расчеты 1С:Зарплата и кадры государственного учреждения 3 Государственные, бюджетные структуры Россия Бюджетный учет Платные (руб)

Расширение конфигурации, включающее в себя объекты, необходимые для подготовки и сдачи отчета "Штатная численность" системы "БОР-Навигатор.Культура" в программе "1С:Зарплата и кадры государственного учреждения", редакция 3.1.

8400 руб.

01.02.2019    25741    9    0    

7

Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС

Обмен с ГосИС WEB-интеграция Платформа 1С v8.3 Управляемые формы 1С:Комплексная автоматизация 1.х 1С:Бухгалтерия 2.0 1С:Управление торговлей 10 1С:Управление производственным предприятием 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия государственного учреждения 1С:Документооборот 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Платные (руб)

Обработка является альтернативой механизму, разработанному фирмой 1С и заполняющему реквизиты контрагента по ИНН или наименованию. Не требуется действующей подписки ИТС. Вызывается как внешняя дополнительная обработка, т.е. используется, непосредственно, из карточки контрагента. Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС (egrul.nalog.ru) для БП 2.0, БП 3.0, БГУ 1.0, БГУ 2.0, УТ 10.3, УТ 11.x, КА 1.1, КА 2.x, УПП 1.x, ERP 2.x, УНФ 1.5, УНФ 1.6, УНФ 3.0, ДО 2.1

2400 руб.

28.04.2016    88582    160    215    

318
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. Steelvan 302 24.06.20 13:14 Сейчас в теме
Все эти технические форматы далеки от обычного человекочитаемого восприятия.

Вот например два похожих продукта (компонента для веб-гнезд) от разных разработчиков.

Бесплатная libwebsockets
https://libwebsockets.org/lws-api-doc-v4.0-stable/html/modules.html

Платная
https://cdn.nsoftware.com/help/IWF/bcb/

---

Да я лучше 30 000 заплачу сверху, но зато получу нормальную человекочитаемую доку.
Разбираться в бесплатном варианте буду дольше, чем эту 30-ку заработаю => время деньги.
2. malikov_pro 1292 24.06.20 13:24 Сейчас в теме
(1) В итогах показал внешний вид для "обычного человекочитаемого восприятия", конвертация делается утилитой через командную строку (у меня в проектах bat файлы для этого).
Примеры
https://www.sima-land.ru/api/v3/help
https://api.samsonopt.ru/v1/doc/index.html#api-v1-0-0
сформированы из OpenAPI (swagger).

Подобное можно формировать и из RAML https://docs.api-console.io/

У вас в примере WebSocket, у меня HTTP, разные протоколы и инструменты описания.
Оставьте свое сообщение