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

Публикация № 1255213

Разработка - Системная интеграция - Интеграция с 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. Steelvan 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 401 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, разные протоколы и инструменты описания.
Оставьте свое сообщение

См. также

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

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

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

10.03.2016    55336    Serginio    33    

Самый простой парсинг и обработка веб-страниц в 1С

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

Рассмотрим самый простой парсинг веб-страниц средствами платформы 1С и еще некоторые полезные приемы работы с веб-страницами.

вчера в 09:03    969    YPermitin    12    

Загрузка или обновление файла на гугл диске

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

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

06.08.2020    164    pavelpribytkin96    0    

Использование Yandex Translate (Яндекс.Переводчик)

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

В статье опишу вариант подключения и использования Yandex Translate.

08.07.2020    1459    malikov_pro    6    

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

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

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

10.03.2017    25663    ruha    14    

Когда хотим знать IP клиента...

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

В процессе разработки web приложения на 1С, и это не шутка))), а пожелание заказчика, возникла ситуации когда понадобилось знать, с какого IP подключался клиент.

03.07.2020    2563    IMihalev    8    

Ограничение доступа к HTTP публикациям 1С сервера используя NGINX

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

В статье опишу вариант ограничения доступа к HTTP публикациям 1С сервера используя NGINX.

02.07.2020    5443    malikov_pro    0    

Структура обработки загрузки цен и остатков поставщика с примерами и комментариями

Внешние источники данных WEB v8 1cv8.cf Россия Бесплатно (free)

В статье опишу структуру обработки по загрузке цен и остатков от поставщика с примерами.

27.06.2020    1416    malikov_pro    0    

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

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

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

12.09.2014    40688    Malfarion    34    

Вариант использования документа "Операция по Яндекс.Кассе" для других сервисов по оплате через интернет

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

В статье рассмотрю организацию эквайринга в УТ 11.4 и доработки для создания заказов на оплату к стороннему сервису, как пример Сбербанк.

24.06.2020    858    malikov_pro    3    

Работа с AliExpress через API

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

В публикации опишу подход работы с API AliExpress и примеры кода.

23.06.2020    2539    malikov_pro    7    

Не программируй - вставляй и копируй. OAuth 2.0 авторизация API Google, получение токенов доступа (refresh и access token)

WEB Облачные сервисы, хостинг Бесплатно (free)

Без программирования, в несколько кликов - простой и быстрый способ трехногой авторизации по протоколу OAuth 2.0 в Google APIs. Получение refresh и первого access token для использования в HTTP-запросах из 1С к API Google. Для приложений типа "Компьютеры".

09.06.2020    2576    uno-c    0    

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

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

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

11.04.2013    40932    YPermitin    34    

История создания успешной системы чат-ботов на 1С

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

Использование чат-ботов в мессенджерах позволяет автоматизировать многие сложные бизнес-процессы путем диалога с системой через виртуального собеседника. О том, как создать универсальную систему ботов с бэкендом на 1С, работающую в Telegram, Viber и Facebook Messenger одновременно, на конференции Infostart Event 2019 Inception рассказал программист-фрилансер Константин Гейнрих.

21.05.2020    6487    CyberCerber    14    

Парсинг html страниц с выводом информации через JavaScript с использованием Selenium

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

Есть девочки как девочки, есть мальчики как мальчики, есть сайтики как сайтики, но странички их обманщики. В целях сохранить информацию, от автоматизированного сбора, многие ресурсы пытаются защитить ее. Один из таких способов - вывод информации на странице через JavaScript. При получении такой страницы в 1С, JavaScript не успевает вывести необходимые данные, и в 1с получаем практически пустую страницу. В статье приведу пример разработки, для парсинга таких страниц, без регистрации и смс.

20.05.2020    2853    platonov.e    25    

Как разработать Web приложение и остаться 1С-ником

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

Создание современных веб-приложений обходится для бизнеса дорого и требует постоянной актуализации различных фреймворков, что не всегда оправданно. Как применить инженерный подход и предоставить бизнес-пользователям доступ к данным 1С в удобном и защищенном веб-приложении на конференции Infostart Event 2019 Inception рассказал руководитель управления ИТ компании WiseAdvice Олег Филиппов.

18.05.2020    11288    comol    86    

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

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

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

03.06.2013    30281    anig99    6    

Интеграция 1С и CMS WordPress посредством Rest API сайта. Шаг третий, WooCommerce, публикация категорий товаров

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

Интеграция 1С и CMS WordPress посредством функционала Rest API. Используем только язык программирования 1С и штатный функционал Rest API предоставляемый CMS, без дополнительных библиотек и плагинов. Процедуры и функции публикации категорий товаров в магазин WooCommerce, с комментариями внутри.

13.05.2020    2477    osivv    3    

Интеграция 1С и CMS WordPress посредством Rest API сайта. Шаг второй, публикация картинок

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

Интеграция 1С и CMS WordPress посредством функционала Rest API. Используем только язык программирования 1С и штатный функционал Rest API предоставляемый CMS, без дополнительных библиотек и плагинов. Процедуры и функции передачи фото из 1С, с комментариями внутри.

13.05.2020    1876    osivv    0    

Интеграция Camunda BPM и 1С

WEB Интеграция v8 Бесплатно (free)

Быстрый старт. Только практические примеры. Установка, запуск и публикация бизнес-процесса на сервере Camunda BPM. Управление бизнес-процессами из 1С при помощи Camunda REST API.

12.05.2020    3158    zhichkin    19    

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

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

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

31.08.2012    28686    avhrst    13    

Интеграция 1С и CMS WordPress посредством Rest API сайта. Первый шаг

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

Интеграция 1С и CMS WordPress посредством функционала Rest API. Используем только язык программирования 1С и штатный функционал Rest API предоставляемый CMS, без дополнительных библиотек и плагинов. Процедуры и функции 1С с комментариями внутри.

28.04.2020    3719    osivv    23    

Выразительный Web API

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

Теория разработки Web API с ожидаемым поведением, за который не будет стыдно за пределами мира 1С.

27.04.2020    5504    nbeliaev    22    

Хранение статистики публикаций автора сообщества Инфостарт ® (мобильное приложение И ++)

Мобильная разработка WEB v8 1cv8.cf Бесплатно (free)

Инфостарт ® достаточно удобный в плане работы со своим личным кабинетом сайт. Но программисты тем и отличаются от большинства людей, что им хочется знать больше. Поэтому появилась конфигурация 1С (она же мобильное приложение 1С) для более подробного учета статистики публикаций: рейтинг, количество просмотров, количество комментариев в динамике и в разрезах.

24.04.2020    2155    capitan    15    

Интеграция УАТ с топливными сервисами

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

Интеграция конфигурации Управление автотранспортом с топливными веб-сервисами.

21.04.2020    7008    RPGrigorev    2    

Интеграция 1С с веб-сервисами Лукойл ЛИКАРД

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

Описание интерфейса взаимодействия сервиса Лукойл- ЛИКАРД с информационной системой 1С.

20.04.2020    3695    RPGrigorev    0    

Как зайти на http://lkul.nalog.ru c VipNet

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

Для тех, кто не может пройти последний пункт "Проверка защищённого соединения с сервером Личного кабинета юридического лица" на сайте http://lkul.nalog.ru/check_cryptopro.php с применением VipNet.

19.04.2020    2316    Voblhned    0    

Ошибка инициализации модуля: HTTPСервис

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

Решение проблемы "Ошибка при работе с HTTP сервисом 500. Ошибка инициализации модуля".

13.04.2020    2559    VipDim    10    

COVID-19. Динамика эпидемии

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

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

01.04.2020    3123    Alejandro_V    6    

Как я собрал для себя высокопроизводительный и бесплатный облачный бекенд для 1С на PosgreSQL + PostgREST

Производительность и оптимизация (HighLoad) WEB Интеграция Мобильная разработка Администрирование веб-серверов v8 Бесплатно (free)

В этой статье я расскажу о проблемах бека для мобильных приложений или другого фронта, который требует производительности, быстрой реакции и отказоустойчивости, и как я решил это благодаря opensource проекту PostgREST и СУБД Postgre SQL 12. Проведу простой тест производительности для сравнения 1С с данным решением. Это может быть полезно всем, кто разрабатывает мобильные приложения либо фронтсайд-приложения для 1С на чем угодно - на мобильной платформе или на нативном языке или на Simple UI. И также обзор новых функций SimpleUI для связи с этим бекендом.

31.03.2020    11881    informa1555    28    

Коронавирус COVID-19. Статистика по странам

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

В связи с COVID-19 люди поделились на две категории: те, кто осознал, и те кто ЕЩЕ не осознал. Единственное наше преимущество перед Коронавирусом заключается в том, что информация распространяется быстрее, чем расползается "невидимка".

25.03.2020    5978    Evgen.Ponomarenko    60    

nsq - еще один менеджер очередей

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

В статье будет описан процесс запуска nsq. Данный mq достаточно прост в использовании по сравнению с другими. Самое главное для меня в этом менеджере, это возможность отправить данные так: http://127.0.0.1:4151/pub?topic=test-messages - вполне достаточно когда 1С выступает поставщиком данных.

05.03.2020    2405    pallid    9    

Первичное взаимодействие с ФГИС МДЛП в аптечной сети на 1С 7.7 (для "чайников"!)

WEB v77::БУ 1С7:Бух Фармацевтика, аптеки Россия БУ ЕНВД Бесплатно (free)

Первичное взаимодействие с ФГИС МДЛП - Федеральной государственной информационной системой мониторинга движения лекарственных препаратов от производителя до конечного потребителя с использованием маркировки в аптечной сети на 1С 7.7 (для «чайников»!).

03.03.2020    2188    umbra777    1    

Получение html-кода страницы. JS из 1С

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

Получение исходника страницы, выполнение произвольного js-кода. Теперь с WebKit от 1С.

18.02.2020    5630    Yashazz    1    

Отладка конфигурации в режиме веб-клиента

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

После очередного обновления платформы при попытке запуска отладки в веб-клиенте стало появляться сообщение. Собственно, до этого момента никогда веб-клиентом особо не пользовался и необходимости в отладке как-то не возникало. Данное сообщение заставило задуматься, что не так с отладкой в веб-клиенте и как ее собственно включить? Тот самый неловкий момент, когда программа просит обратиться к администратору, а администратор - это вы.

12.02.2020    4465    gamletspb    3    

Анализ работы внешней обработки сервиса МодульКасса применительно к задаче фискализации чеков при доставке

Кассовые операции WEB v8 УТ11 Россия Бесплатно (free)

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

11.02.2020    2579    malikov_pro    0    

Вариант реализации работы с сервисом Dadata применительно к конфигурации УТ 11.4 и подобным

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

В статье описывается реализация получения данных с сервиса DaData при работе с формами справочников в конфигурации УТ 11 для дополнения информации по ФИО, ИНН, Адресу.

22.01.2020    3064    malikov_pro    5    

Двусторонний обмен с поставщиком через интернет-магазин для реализации товаров с ответственного хранения (с 01.02.2020 "Партии" не используются)

Файловые протоколы обмена, FTP WEB v8 УНФ Оптовая торговля, дистрибуция, логистика Россия УУ Бесплатно (free)

Рассмотрены реализация двустороннего обмена данными с использованием API-сервиса сайта поставщика при продаже товаров со склада ответственного хранения, алгоритм движения товаров и обмена документами на примере конфигурации 1С: УНФ у партнера, который взаимодействует с поставщиком "ООО Пауэр-Интернэшнл-шины" - одним из крупнейших в России поставщиков автомобильных шин и дисков.

16.01.2020    4268    chkurs    0    

Проброс IP-адреса клиента в http-сервис 1С. Реализация для IIS

WEB Администрирование веб-серверов IIS Бесплатно (free)

Настраиваем веб-сервер IIS для передачи в 1С IP-адреса клиента, вызвавшего http-сервис. Разбираемся с этим же вопросом при использовании фронтэнд вебсервера на примере nginx.

01.12.2019    6043    VKislitsin    9    

Получение номера ВСД по идентификатору 1С: Меркурий

Производство готовой продукции (работ, услуг) WEB v8 УТ11 Пищевая промышленность Россия Бесплатно (free)

Код парсинга веб страницы для получения номера ВСД в системе Меркурий.

24.11.2019    4292    ohyen    0    

Немного о интеграции с CRM AMO

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

Немного информации о том, как настроить интеграцию с CRM AMO. Пример функций для подключения к АМО и обновления заказа. Пример на основе API авторизации.

15.11.2019    4249    xxxAndricxxx    6    

Ещё немного о ИНН и сервисе DaData

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

Об использовании сервиса dadata и немного информации о возможностях получать данные по ИНН. Возможно, кому-то будет полезным.

14.11.2019    6885    xxxAndricxxx    21    

Вариант реализации клиента SOAP на примере получения остатков из MERLION

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

В статье приведу пример клиента к сервису SOAP, функции которого принимают несколько значений типа строка или массив строк.

14.11.2019    3400    malikov_pro    0    

Разбор любого JSON-объекта в соответствующую структуру

Инструментарий разработчика WEB v8 1cv8.cf Бесплатно (free)

Данная публикация предназначена разработчикам 1С, которым приходиться разбирать данные формата JSON. Выложенный пример кода создает объект типа Структура, полностью повторяющий структуру данных формата JSON.

13.11.2019    8110    user665435_al.windstorm    15    

Проверка reCAPTCHA от Google на стороне HTTP-Сервиса

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

Код проверяет переданный токен reCAPTCHA от Google при вызове HTTP-Сервиса. Таким образом проверяем, отправил ли данные на наш HTTP-Сервис робот или реальный пользователь.

06.11.2019    5863    AVR    0    

Swagger для 1С.

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

Решение для формирования Swagger спецификаций, описывающих HTTP сервисы конфигураций 1С.

21.10.2019    11784    botokash    40