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

Публикация № 1255213 Дата создания: 24.06.20 12:30

Разработка - Системная интеграция - Интеграция с WEB

RAML API

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

Вводные

Нужно описать документацию на 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
 
 Внешний вид описания ресурса

 

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

Специальные предложения

Комментарии
В избранное Подписаться на ответы Сортировка: Рейтинг 1-го уровня
1. Steelvan 102 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-ку заработаю => время деньги.
Оставьте свое сообщение

См. также

.Net в 1С. На примере использования HTTPClient, AngleSharp. Удобный парсинг сайтов с помощью библиотеки AngleSharp, в том числе с авторизацией аля JQuery с использованием CSS селекторов. Динамическая компиляция Промо

Практика программирования WEB v7.7 v8 Бесплатно (free)

Часто приходится парсить сайты, в том числе с авторизацией, перескакивая со страницы на страницу по ссылкам. Тот, кто занимался вэб программированием, знает, как удобно использовать JQuery и CSS селекторы. На .Net написана очень удобная библиотека AngleSharp. Я покажу, как с её помощью можно значительно облегчить себе труд.

10.03.2016    57644    Serginio    33    

Телеграм-бот как инструмент

WEB v8 1cv8.cf Бесплатно (free)

Статья больше для начинающих программистов о том, как можно помочь самому себе при доработке 1С или при разработке собственных решений.

21.07.2021    1555    M_A_D    14    

Доработка в расширении Яндекс маркета (скачать все этикетки)

Практика программирования WEB v8 УТ11 КА2 Бесплатно (free)

Доработка кнопки "Скачать все этикетки" - выбрали каталог и сохранили все за один раз, а не 100500 раз нажимаем кнопку сохранить.

08.07.2021    707    rst_filippov    0    

Интеграция 1С 8 и HostCMS

WEB v8 1cv8.cf Бесплатно (free)

Интеграции 1С с сайтами очень сложно оценивать, ибо на сайте разработчика CMS, а может, и на странице конкретного модуля, зачастую можно найти инструкцию подключения обмена, но в ходе работы постоянно появляются подводные камни: то одно не выгружается, то другое, порой, кажется, все данные передаются, но документы или элементы справочников не заполняются. А перерабатывать типовой механизм зачастую бывает себе дороже. Причем бывают и ситуации, когда нужно вносить изменения и в 1С, и на сайте. Стоимость таких работ возрастает и встает вопрос о том, нужно ли это вообще. Сейчас я расскажу о том, как мы подключали HostCMS, а в конце статьи приведу результаты обмена.

04.07.2021    510    Koder_Line    0    

Online телефонный справочник из 1С: Зарплата и управление персоналом Промо

WEB Управление персоналом (HRM) Управление персоналом (HRM) v8 ЗУП3.x Россия Бесплатно (free)

В интернете представлено много реализаций online телефонных справочников организаций. Есть справочники, которые использует для хранения информации базу Active Directory (LDAP), есть справочники, которые реализованы с использованием СУБД (например, MySQL). Но я не нашел справочника, который использует информацию из базы 1С. Далее я рассмотрю данную разработку.

10.03.2017    26833    ruha    21    

API ОФД-Я разбор документации с примерами

WEB v8 1cv8.cf Россия Бесплатно (free)

Примеры запросов 1С для получения данных с ОФД-Ярус через API.

20.04.2021    670    www76    0    

FastAPI (python) - инструмент для быстрого создания Веб сервиса (WSGI) с REST api

WEB Бесплатно (free)

Ознакомительная статья по FastAPI (python) - инструменту быстрого создания Веб сервиса (WSGI) с REST api.

19.04.2021    4805    Идальго    23    

Работа через сервис 1С-Отчетность нескольких пользователей

Регламентированная отчетность Зарплата WEB v8 v8::СПР ЗУП3.x Россия БУ ФОМС, ПФ, ФСС Бесплатно (free)

Организации, в которых количество сотрудников превышает установленное значение, обязаны отправлять отчетность по телекоммуникационным каналам связи. Это может быть Контур-Экстерн, Такском или любой другой провайдер. Все чаще пользователи 1С используют сервис 1С-отчетность. И все чаще сертификат оформляется на сотрудника отдела кадров или бухгалтерии. В случае, если нужно оформить несколько сертификатов, возникают трудности в версии ЗУП 3.1.14 и более поздних. О том, как с ними справиться, пойдет речь в данной публикации.

05.04.2021    1413    keat24    1    

Информер для сайта , актуальные релизы 1С + Проверка подписки ИТС. Промо

WEB Администрирование данных 1С Сервисные утилиты Бесплатно (free)

Небольшой код который встраивается на сайт и выводит информацию о последних релизах конфигураций 1С

12.09.2014    41066    Malfarion    34    

Wildberries. Заполнение карточек товаров. Как получить значение справочников?

WEB Бесплатно (free)

Wildberries. Заполнение карточек товаров. Как получить значение справочников? в документации это описано очень скромно, пытаюсь рассказать на основании своего опыта.

31.03.2021    1376    sergeyisa    1    

Как получить ключ поставщика Wildberries (uuID), supplierID, Идентификатор поставщика

WEB Бесплатно (free)

Как получить ключ поставщика Wildberries (uuID), supplierID, Идентификатор поставщика, для работы с карточками товара.

18.03.2021    1275    sergeyisa    7    

Правила обмена больше не нужны

Внешние источники данных Обмен через XML Перенос данных из 1C8 в 1C8 Распределенная БД (УРИБ, УРБД) WEB v8 Бесплатно (free)

Есть несколько общепринятых подходов к написанию обмена между 1С-системами, каждый из которых упирается в длительное изучение технологии, мучительную отладку правил конвертации и написание большого количества сервисного кода, в котором потом тяжело разобраться. О принципах работы универсального фреймворка liteExchange, который реализует быстрые обмены между 1С и внешними системами, и берет на себя всю техническую обвязку по стандартному преобразованию данных, на INFOSTART MEETUP Saint Petersburg.Online рассказал Николай Крылов.

17.03.2021    9652    Nikola23    36    

Кэширование COM-соединения. Три способа Промо

Практика программирования Перенос данных из 1С7.7 в 1C8.X Внешние источники данных WEB v8 Россия Бесплатно (free)

Статья о трех способах кэширования COM-соединения в 1С:Предприятии 8.x.

11.04.2013    42689    YPermitin    41    

Интеграция "1С:Управление торговлей 10.3" с Yandex SpeechKit для распознавания телефонных звонков

WEB Интеграция Телефония, SIP Бесплатно (free)

Распознавание телефонных звонков позволяет контролировать работу менеджеров, организовать для них дополнительный KPI, помогает разбирать конфликты и категоризировать звонки по вхождению слов. О своем опыте интеграции «1С:Управления торговлей 10.3» и сервиса Yandex SpeechKit на INFOSTART MEETUP Saint Petersburg.Online рассказал ИТ-директор компании «Умный дом» Федор Рыжков.

12.03.2021    925    zzhiraf_    0    

Как отправить сообщение Telegram в группу?

WEB v8 Россия Бесплатно (free)

Отправка сообщения в группу Telegram.

01.03.2021    1480    kite2    2    

Альфа-Авто 5.0 и современные HTTP сервисы

WEB v8 1cv8.cf Автомобили, автосервисы УУ Бесплатно (free)

Решение, позволяющее программным продуктам, работающим на устаревших версиях платформы 1С (8.2), интегрироваться с современными HTTP сервисами. Решение, интегрированное с HTTP-сервисом программы по расчету компонентов для изготовления ЛКМ, описанное в настоящей статье, успешно работает в одном из автосервисов, работающем на устаревшей платформе и конфигурации Альфа-Авто 5.0.

01.03.2021    827    osivv    1    

Заготовка для загрузки файлов по ftp Промо

WEB Перенос данных из 1C8 в 1C8 v8 1cv8.cf Бесплатно (free)

3 процедуры и 1 макет

03.06.2013    31067    anig99    6    

Доступ из базы 1С к стандартному интерфейсу Odata базы 1С, в которой заведен пользователь

WEB v8 Россия Бесплатно (free)

Есть база, с пользователем/паролем, нужно подключиться к Odata из другой базы 1С, получить элементы справочника.

24.02.2021    828    user823999    6    

Бот Telegram и HTTP сервис в 1С

WEB 8.3.8 Бесплатно (free)

Настройка рабочего вебхука telegram для 1С используя IIS (Internet Information Services - встроенный в windows веб-сервер). Мой опыт.

26.01.2021    6684    solidsun    11    

Интеграция с API WB (Wildberries). Создание карточки товара (спецификации)

WEB v8 1cv8.cf ИТ-компания Россия Бесплатно (free)

Опыт интеграции с API WB (Wildberries), опыт создания карточки товара, получение токенов API WB.

18.01.2021    18756    jenyavp    54    

Организация удаленного доступа к корпоративной информационной системе — это просто ! Промо

Внешние источники данных Монитор заказов WEB Монитор заказов Бесплатно (free)

Хочу поделиться своим опытом создания web морды к корпоративной информационной системе на базе 1С. Необходимо организовать сбор заказов от удаленных пользователей. - Каждый пользователь видит свой набор данных, и работает со своими документами. - Доступ по логину/паролю, работа в основном с планшетов (iPad) или с десктопа. - Сервер должен находиться за пределами организации. - Себестоимость 1 пользователя не более 10$ за месяц. - Использование в основном мобильного канала связи GPRS (~100 КБ/с).

31.08.2012    28987    avhrst    13    

1С и Умный Дом. Управление голосом

WEB Интернет вещей (IIoT) 8.3.6 Бесплатно (free)

Возможно ли управление устройствами умного дома из 1С, да ещё и голосом? Можно ли без умных колонок Google Home, Alexa, Алиса и иных платформ, а также без приложений от Google, Amazon и других управлять этими устройствами? Мой ответ – ДА, можно, нужно просто иметь умное устройство, имеющее возможность работы в DIY, 1С и программу распознавания голоса и взаимодействия с 1С.

04.01.2021    2287    osivv    15    

HTML редактор/editor (Wysiwyg) для WebKit 1С (CMS, B2B), альтернатива TinyMCE и стандартному ФорматированныйДокумент

WEB Интеграция v8 v8::УФ 1cv8.cf Бесплатно (free)

Suneditor - отличная замена HTML редактору TinyMCE (бесплатному), в публикации с открытым кодом подключим его в 1С с WebKit, скачать HTMLeditor обработку можно бесплатно.

28.12.2020    2983    SizovE    25    

1С и Умный дом

WEB Интернет вещей (IIoT) 8.3.8 Бесплатно (free)

Возможно ли управление устройствами умного дома из 1С? Можно ли, минуя сложные настройки ZigBee, Z-Wave и иных платформ, а также без приложений от Google, Amazon и других управлять этими устройства? Мой ответ – ДА, можно, нужно просто иметь умное устройство, имеющее возможность работы в DIY, ну и, естественно, 1С.

21.12.2020    1976    osivv    8    

[TinyMCE] - редактор HTML WYSIWYG. Интеграция во все виды управляемого и обычного приложения

WEB 8.3.14 Бесплатно (free)

В статье рассмотрены вопросы использования во всех режимах работы 1С Предприятие 8.3 редактора TinyMCE в поле HTML дополнительного функционала.

14.12.2020    1090    user1206119    0    

Выгрузка HTML описаний с картинками (Base64) товаров на сайт/интернет-магазин/B2B, разберем регулярное выражение получения тега body, ПолучитьHTML, ФорматированныйДокумент

Практика программирования WEB Универсальные функции v8 v8::УФ 1cv8.cf Бесплатно (free)

Редактор HTML платформы 1С простой и очень удобный для небольших задач, однако ПолучитьHTML возвращает отдельно картинки и отдельно целиком HTML страницу со ссылкой на имена этих картинок, что неудобно для отправки в базу данных сайта/интернет-магазина/веб-приложения/B2B. Разберем на открытом коде, как решить эту проблему, напишем универсальную функцию получения значения любого тега HTML на регулярных выражениях. Бонусом - возможность редактировать теги HTML в текстовом режиме.

24.11.2020    1019    SizovE    4    

Как сделать интеграцию (обмен) с интернет-магазином? Пошаговый план действий (Часть 1)

WEB v8 1cv8.cf УУ Бесплатно (free)

C 2011 года я занимаюсь интеграцией с интернет-магазинами и за это время, наверное, повидал все. Делал интеграцию как «культурными», так и «экзотическими» способами. Количество магазинов исчисляется сотнями. В этой серии статей я буду делиться своим опытом, а также выкладывать какие-то полезные наработки.

19.11.2020    6413    markbraer    11    

Чтение вложенных свойств Структур Структуры, Соответствий, свойства через точку, разбор JSON

Практика программирования WEB Интеграция Универсальные функции v8 Бесплатно (free)

JSON: {user.device.type} - как получить значение {type}? А если вложенность значительно глубже? Как проверить, что оно заполнено или удалить его - всё это в публикации с открытым кодом и даже без рекурсии. Бонусом разбор дерева значений - ДанныеФормыЭлементДерева, СтрокаДереваЗначений.

17.11.2020    1966    SizovE    2    

Web Dashboard (мобильная и десктопная версия): оптимальная схема организации взаимодействия с зоопарком систем

WEB v8 Бесплатно (free)

Задача: из множества систем (1С:ERP, 1C:CRM, Кронос:WMS, 1С:Розница, 1С:УПП...) оперативно и онлайн осуществлять мониторинг на телефоне/десктопе/планшете/телевизоре бизнес-аналитику в дашборде для директора. Рассмотрим в статье, как правильно интегрировать между собой все базы, какие для этого инструменты использовать.

10.11.2020    10444    SizovE    2    

Как я бесплатно пишу чат-ботов WhatsApp на 1С

WEB Бесплатно (free)

На разработку чат-бота требуется время. Как правило, время уходит на ознакомление с API, отладку, приемку. Как сэкономить и не платить за использование API на время разработки? Делюсь своим опытом.

02.11.2020    2707    andrew_shamin    10    

Отладка модуля ДиадокПро

WEB v8 1cv8.cf Бесплатно (free)

В обработке ДиадокПро все дополнительные модули встроены во внешние обработки, которые хранятся в макетах. Это усложняет процесс самостоятельной интеграции, так как теряется возможность попасть в них в режиме отладки. Но не всё так страшно, поэтому ниже инструкция)

30.10.2020    3111    Максим-777    14    

JSON примеры меню B2B web-приложения "Личный кабинет" на движке EDIbot для телефона/десктопа

WEB v8 Бесплатно (free)

Рассмотрим на примерах работу движка EDIbot при организации меню B2B "Личного кабинета" (мобильная версия, версия десктоп) грузовладельца WMS-системы.

29.10.2020    1168    SizovE    0    

Обмен с сайтом посредством Post-запроса, json

WEB v8 1cv8.cf Бесплатно (free)

Задача - передавать на сайт объекты с наименованием и уникальным идентификатором (УИ), которые изменяются в 1С. Также нужно сохранять историю отправленных пакетов.

29.10.2020    5048    John_d    26    

Организация HTTP публикации каталога товаров используя PostgREST

WEB v8 1cv8.cf Бесплатно (free)

В статье опишу порядок установки настройки и использования PostgREST на примере организации каталога товаров.

05.10.2020    1364    malikov_pro    2    

Использование HTTP REST обертки xmysql для работы с MySQL на примере OpenCart

WEB Бесплатно (free)

В статье опишу вариант работы с MySQL базой используя HTTP.

28.09.2020    2171    malikov_pro    2    

Интеграционная прослойка(middleware) на Golang. Часть 5 - Обмен с 1С через HTTP-сервисы платформы

WEB v8 Бесплатно (free)

В этой статье научим прослойку отправлять данные в 1С, для этого используем HTTP-сервисы платформы. Обменяемся данными с новым справочником Клиенты. Но главное создадим HTTP-сервис для получения сообщений из очереди RabbitMQ.

28.09.2020    2289    dmitry-irk38    4    

Отладка http сервиса

WEB v8 Бесплатно (free)

При разработке http сервиса возникает ситуация, а как протестировать http сервис? Создали мы сервис, настроили шаблоны, передали, если нужно параметры, открываем браузер заполняем строку подключения и БАХ, ошибка. Что делать?

23.09.2020    4043    hpi    12    

Учимся создавать http сервисы (часть вторая). Передача параметра в http сервис

WEB v8 1cv8.cf Бесплатно (free)

Пошаговое руководство по созданию http-сервиса (часть вторая). Передача параметра в http сервис.

22.09.2020    7151    hpi    7    

Организация данных и вариант обработки для организации обмена с сайтом

WEB v8 1cv8.cf Бесплатно (free)

В статье опишу вариант организации данных и обработки для обмена с сайтом.

22.09.2020    1703    malikov_pro    4    

Формирование списка документов и скачивание печатной формы документа через веб-сайт с использованием HTTP-сервиса, плюс особенности авторизации

Практика программирования Обмен данными 1С WEB v8 1cv8.cf Бесплатно (free)

В статье показан пример, как реализовать формирование списка документов клиента/пользователя по коду, а затем скачать его (документа) печатную форму по ссылке

18.09.2020    1378    R_o_n_n_y    3    

Формирование HTTP запроса формата multipart/form-data с двоичными данными, используя ПотокВПамяти

WEB v8 1cv8.cf Бесплатно (free)

В статье опишу вариант формирования запроса

11.09.2020    4510    malikov_pro    11    

Дневник боли и страданий. Как я переходил от The Bat! к MS Outlook

WEB Бесплатно (free)

Мой опыт перехода от The Bat! к MS Outlook. Сравнение двух программ, киллер-фичи, лайфхаки и рецепты из интернета. Все в одном месте и проверено автором на актуальных релизах сентября 2020 года.

02.09.2020    2436    gubanoff    15    

Формирование документа Google Docs из шаблона используя Google Apps Script

WEB Бесплатно (free)

В статье опишу работу скрипта для формирования документа с публикацией по HTTP.

25.08.2020    2297    malikov_pro    3    

Ферма приложений на Kubernetes

WEB v8 Бесплатно (free)

При эксплуатации большого количества информационных систем 1С, предоставляющих интернет-сервисы, возникают проблемы, связанные с зависимостью от производительности и стабильности веб-сервера. Как объединить отдельно стоящие веб-сервера с помощью платформы Kubernetes для централизованного мониторинга всех опубликованных интернет-сервисов на конференции Infostart Event 2019 Inception рассказал программист компании BIA Technologies Владимир Кирбаба.

24.08.2020    2143    ComboBoy    1    

Использование шаблонного процессора для формирования HTML страниц

WEB v8 1cv8.cf Бесплатно (free)

В статье опишу использование шаблонного процессора Handlebars запущенного на Node.js

24.08.2020    1886    malikov_pro    26    

Использование скриптов при формировании запросов используя Postman

WEB Бесплатно (free)

В статье опишу применение JS скриптов а postman при работе с API.

22.08.2020    3976    malikov_pro    8