HTTP сервисы по OpenAPI спецификациям

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

Разработка - Практика программирования

OpenAPI Swagger RestAPI HTTP сервисы

Начинаем путь разработки HTTP сервисов с создания спецификаций OpenAPI. Автодокументация сервисов формата Swagger UI без зависимостей. Настройка сервисов в режиме предприятия.

        


Зачем это надо

  • Убрать разрыв между написанием кода и подготовкой документации
  • Всегда соответствующие документации сервисы
  • Унифицированный контроль соответствия поступивших запросов спецификации
  • Возможность унифицированного контроля формируемых ответов спецификации
  • Онлайн документацию формата Swagger UI средствами самого 1С сервиса без внешних зависимостей
  • Разделение этапов разработки интерфейса и реализации функционала
  • Выделение конечного функционала по обработкам
  • Возможность назначения обработчиков конечных точек сервиса в режиме предприятия
  • Возможность создавать в конечных обработчиках "долгоживущие" объекты

Требования

1С Предприятие версии >= 8.3.9

Установка

Проект на Gitlab

Использование

Простейшая конфигурация HTTP сервиса в конфигурации/расширении (нового)

В общем случае требуется один ресурс с шаблоном /* и одной конечной точкой, обрабатывающей все http-методы

Обработчик входящего запроса состоит из единственного вызова

    Возврат оас_Сервис.Ответ(Запрос);
Разрабатываем спецификацию сервиса в формате OpenAPI v3.x, сохраняем в формате JSON

например используя визуальный редактор

Настройка сервиса в обработке "ОАС. Управление сервисами"

(на скриншоте отмечены номера пунктов в интерфейсе)

Обработка Управление сервисами

  1. Выбрать HTTP-сервис
  2. Загрузить спецификацию в 1С
  3. Получаем шаблон модуля обработки, вызываемой при получении запросов к выбранной точке
    1. Создаем обработку в конфигурации или расширении
  4. Копируем текст шаблона в модуль объекта созданной обработки, реализуем функционал
  5. Выбираем созданную обработку как обработчик запросов конечной точки сервиса

Повторяем пункты 3-5 для каждой конечной точки.

Шаблон модуля обработки (4) содержит комментарии, содержащие информацию о спецификации конечной точки

  • Имена сервиса, конечной точки, HTTP метода
  • Параметры, их обязательность
  • Тип тела запроса, его обязательность, при наличии в спецификации схема содержания
  • Схема тела ответа по спецификации

Автоматически формируемая сервисом документация

Тема "Просмотр"

Тема Просмотр

Тема "Чтение"

Тема Чтение

Для формирования страниц документации используется библиотека RapiDoc (возможности модификации вывода), позволяющая настраивать

  • Темы
  • Компоновку
  • Схему
  • Логотип
  • ...

 

Схема выполнения сервиса

 

Ссылки

Демонстрационная база

Скачать

Пример vrd файла для публикации HTTP сервиса расширения

Загружены типовые демонстрационные правила OpenAPI (Pets), для примера можно вызвать опубликованный сервис без параметров (с ошибочными параметрами).

История изменений

Релизы на Gitlab

0.2.4.3 

  • Добавлено Сохранение/Загрузка настроек сервиса в файл, не изменяя спецификации
  • Реализация хранения настроек в базе через отдельный адаптер. Вид адаптеров "ОАС. Хранение настроек". Управление в обработке "ОМ. Управление адаптерами"

0.1.4.19

  • Первая публикация

 

Скачать файлы

Наименование Файл Версия Размер
HTTP сервисы по OpenAPI спецификациям: сборка 0.2.4.3
.zip 700,76Kb
30.06.20
0
.zip 0.2.4.3 700,76Kb Скачать
HTTP сервисы по OpenAPI спецификациям: демонстрационная база 0.2.4.3
.dt 1,16Mb
30.06.20
0
.dt 1,16Mb Скачать
HTTP сервисы по OpenAPI спецификациям: сборка 0.1.4.19
.zip 693,18Kb
30.06.20
0
.zip 0.1.4.19 693,18Kb Скачать
HTTP сервисы по OpenAPI спецификациям: демонстрационная база 0.1.4.19
.dt 871,64Kb
30.06.20
1
.dt 871,64Kb 1 Скачать

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

Комментарии
Избранное Подписка Сортировка: Древо развёрнутое
Свернуть все
1. cprit 314 29.06.20 19:59 Сейчас в теме
Спасибо. То чего давно не хватало
Если автор не против, включу в универсальные инструменты 1С https://github.com/cpr1c/tools_ui_1c. Лицензия в репозитории позволяет
2. shmalevoz 201 29.06.20 20:15 Сейчас в теме
(1) Конечно не простив, включайте. У вас кстати ссылка битая. Верна https://github.com/cpr1c/tools_ui_1c
3. cprit 314 29.06.20 20:16 Сейчас в теме
(2) Видимо из-за скобок было. Поправил комментарий
4. Xershi 976 29.06.20 22:18 Сейчас в теме
Насколько я понял это сервис, который 1 раз опубликовал и дальше пилишь справочники в предприятии и сразу генерируется документация?
У самого была такая идея, но не было задач для реализации конечного варианта.
Единственное авторизация есть на уровне сервиса или пилится кодом?
Аналогично разделение прав?
5. shmalevoz 201 29.06.20 22:46 Сейчас в теме
(4) Это прослойка между входящим запросом и конечным функционалом расположенным в обработках. Может обслуживать произвольное количество сервисов конфигурации. Для каждого сервиса своя спецификация.
На входе нужны
1. HTTP сервис, достаточно одного ресурса сервиса с шаблоном /* и одной конечной точкой с обработкой любого http метода. Обработчик точки может содержать только Возврат оас_Сервис.Ответ(Запрос)
2. Спецификацию OpenAPI v3 в формате json. Делается визуальными редакторами/руками
В обработке управления загружаем спецификацию, получаем шаблоны модулей конечных обработок. Создаем обработки, копируем шаблоны для конечных точек, наполняем их смыслом. Назначаем вызовы созданных обработок для конечных точек сервиса.
Расширение выполняет контроль соответствия входящего запроса загруженной спецификации. Единая точка проверки. И далее по настройкам вызывает конечные обработки реализующие логику точек. Есть события ПередОбработкойЗапроса, ПослеОбработкиЗапроса, обработчики назначаемы. Плюс на основании спецификации формирует документацию в распространенном юзерфрендли формате. Конечную логику (авторизацию) не изменяет.
Справочники не использует, все хранится в ХранилищеСистемныхНастроек
JohnyDeath; +1 Ответить
6. Xershi 976 30.06.20 10:37 Сейчас в теме
(5) я так понимаю сделано чтобы снизить совместимость решения?
Лучше тогда сделать 3 варианта, конфигурация до 8.3.6, хранилище до момент использования справочников 8.3.11 и использование справочников в расширении.
Для заметок сделал публикацию Эволюция расширения конфигурации. С 8.3.11 доступно создавать свои справочники, а сейчас типовые уже 8.3.12+.
7. shmalevoz 201 30.06.20 10:52 Сейчас в теме
(6) Не вижу смысла пилить справочники для хранения набора условно константных соответствий с текстовым содержанием. Тем паче это данные расширения. Для этих целей очень неплохо подходит ХранилищеНастроек, как раз они там и хранятся. А совместимость с 8.3.9 сложилось достаточно исторически, при разработке базовых зависимостей, не помню уже какой там метод использовался, надо тесты запускать на младших платформах.
Относительно решения в конфигурации, то расширение в конфигурацию конвертируется легко - в Configuration.xml расширения меняется узел <Properties> на узел из конфигурации и загружается из файлов. Получается готовая конфигурация. Работающим на старых релизах + полчаса работы с перекурами.
8. botokash 244 30.06.20 11:03 Сейчас в теме
(7) А как происходит миграция загруженных настроек работы сервиса в РИБ?
9. Xershi 976 30.06.20 11:25 Сейчас в теме
(8) судя из ответов автора никак. РИБ же переносит только пользовательские данные. А "ХранилищеНастроек" это служебные.
10. shmalevoz 201 30.06.20 11:32 Сейчас в теме
(9) Да, на РИБ текущая реализация не рассчитана, понадобится модификация чтения/записи настроек. Надо будет в будущем сделать адаптер хранения настроек чтобы управлять этим делом.
11. Xershi 976 30.06.20 11:33 Сейчас в теме
(10) перейдя на 1 и 3 вариант это не понадобится.
12. shmalevoz 201 30.06.20 11:36 Сейчас в теме
(11) Как раз использование адаптера позволит не менять расширение, а вызывать необходимую выбранную реализацию хранения.
14. Xershi 976 30.06.20 11:39 Сейчас в теме
(12) в любом случае хранение через справочники надежнее. Если инфа в хранилище побьется или будет удалена не очень приятно будет)
18. shmalevoz 201 01.07.20 10:17 Сейчас в теме
(14) В свежей версии появился адаптер хранения настроек, можно использовать любую собственную реализацию хранилища
17. shmalevoz 201 01.07.20 10:16 Сейчас в теме
(8) Теперь можно хранить настройки где угодно - делаем обработку с интерфейсом как в оас_НастройкиХранилищеСистемныхНастроек, выбираем ее адаптером хранения настроек в ОМ. Управление адаптерами (вид ОАС. Хранение настроек) и управление по чтению/записи настроек передается на нее. А там уж где хоть справочник, хоть регистр сведений, что угодно
13. shmalevoz 201 30.06.20 11:37 Сейчас в теме
А там уж кто какую схему хранения использует это дело хозяйское =)
15. malikov_pro 303 30.06.20 14:58 Сейчас в теме
в модуле опечатка, style по идее.

Буду рад если поделитесь опытом ведения проекта в git и его сборки.
16. shmalevoz 201 30.06.20 15:09 Сейчас в теме
19. shmalevoz 201 01.07.20 10:21 Сейчас в теме
(15) Не вопрос, поделюсь. Только вопрос больно расплывчатый. В личку пожалуйста, кажется вопрос объемен и лучше там обменяться контактами
Оставьте свое сообщение

См. также

Работа с картой. Кадастровый учет (Росреестр). Тематические карты Промо

WEB Рабочее место v8 v8::УФ 1cv8.cf Абонемент ($m)

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

5 стартмани

31.08.2017    15830    10    vipchep    0    

Пример использования REST API Яндекс Диска

WEB v8 1cv8.cf Абонемент ($m)

Пример использования REST API Яндекс Диска: чтение диска, добавление каталога, загрузка файла, скачивание файлов или каталогов, удаление файлов или каталогов.

1 стартмани

26.06.2018    21374    33    MKFreeUser    14    

Обмен файловыми базами данных через Yandex диск

WEB v8 Россия Абонемент ($m)

Выполнение операций обмена с Yandex диском для файловых БД, по протоколу WebDav, в автоматическом или ручном режимах.

1 стартмани

11.06.2018    15342    5    slimper    1    

Построение маршрута доставки с расчётом расстояния для любой базы УФ

Универсальные обработки WEB Оптовая торговля Оптовая торговля v8 v8::УФ 1cv8.cf Абонемент ($m)

Графическое изображение маршрутного листа по картам гугл. Работает на любой конфигурации с управляемыми формами. Использует новую версию api google-карт от 13.02.2018 года под IE11.

10 стартмани

24.02.2018    32362    41    KorotkovRV    16    

Парсинг и анализ топ рейтинга Самиздата (samlib.ru) v2.02 (СКД, XPath, Управляемые и обычные формы) Промо

WEB v8 v8::УФ v8::СКД 1cv8.cf Россия Абонемент ($m)

Хочется почитать хорошую книгу? На сайте Самиздата samlib.ru публикуются сотни интереснейших книг... и тысячи, читать которые далеко не так интересно.

2 стартмани

16.12.2010    27226    26    milkers    16    

Сервер push сообщений “Push0k“ 18.05

WEB v8 1cv8.cf Абонемент ($m)

Аналог других “мессенджеров“. Позволяет практически все то же самое, что и другие решения. За исключением смайлов, эмодзи, голосовой и видео связи. Основное отличие от других решений, открыта и доступна для изменения серверная и клиентская часть месенджера. Общедоступной серверной части нет, за серверную часть отвечаете вы сами.

1 стартмани

19.12.2017    16118    12    PloAl    20    

Настройка рекламной кампании Яндекс.Директ на 30000 ключевых фраз за 60 минут - теперь это реально!

WEB v8 Реклама, PR и маркетинг Россия Абонемент ($m)

Конфигурация для настройки Яндекс.Директа.

10 стартмани

20.10.2016    27678    51    avalakh    10    

Просмотр данных системы Платон на картах Google

Универсальные обработки WEB v8 1cv8.cf Автомобили, автосервисы Транспорт, автопарки, такси Абонемент ($m)

Обработка для просмотра предполагаемых треков движения транспортного средства на карте Google согласно данным, предоставляемым системой Платон в формате CSV. Работает под 8.2 и 8.3, обычное и управляемое приложение, может подключаться к типовым конфигурациям в качестве внешней обработки.

1 стартмани

15.04.2016    30168    18    anig99    8    

Импорт из EXCEL и других источников (xls, xlsx, xlsb, ods, sxc, dbf, mxl, csv, clipboard, sql) в 1С

Загрузка и выгрузка в Excel Внешние источники данных Обработка справочников Практика программирования Обработка документов v8 КА1 БП2.0 УТ10 Розница Беларусь Украина Россия БУ Абонемент ($m)

-Наглядная, контролируемая загрузка иерархической номенклатуры с различными атрибутами и картинками из прайсов, файлов табличного вида xls,xlsx,xlsb,ods,sxc,dbf,mxl,csv произвольной структуры по указанному диапазону строк, а также из буфера обмена и внешнего SQL-источника данных в основные, дополнительные и пользовательские реквизиты. -Вариантный поиск номенклатуры. -Создание сопутствующей справочной информации. -Создание документов в национальной/иностранной валюте. -Обычное и управляемое приложение. Файл и Клиент-Сервер.

1 стартмани

16.03.2012    358414    2843    StepByStep    733    

Загрузка изображений с поисковых сайтов сети Интернет в 1С

Обработка справочников WEB Оптовая торговля Розничная торговля Оптовая торговля Розничная торговля v8 v8::ОУ УТ10 УТ11 Абонемент ($m)

Обработка загрузки изображений из интернета в 1С:Предприятие. Платформа 1С:Предприятие версий 8.2 и 8.3.

5 стартмани

13.10.2015    38754    154    premierex    133    

Автоматическая загрузка классификатора адресов КЛАДР

Обработка справочников WEB v8 УТ10 Россия Абонемент ($m)

Обработка автоматически загружает классификатор с сайта www.gnivc.ru, распаковывает и загружает все регионы в информационную базу.

1 стартмани

02.09.2015    23309    39    kolos    1    

Загрузка товаров с Яндекс.Маркет

Обработка справочников WEB v8 УТ10 Абонемент ($m)

Обработка предназначена для загрузки товаров (их описаний, свойств, изображений) с торговой площадки Яндекс.Маркет в базу Управление Торговлей 11. В отличие от других подобных обработок Вам самим не придется парсить страницы Яндекс.Маркет и решать сопутствующие этому процессу проблемы (бан, капча, поиск прокси-серверов, длительное ожидание результатов при больших объемах данных), так как все данные уже загружены на наш сервер и готовы для использования. Обновление данных осуществляется раз в месяц. Таким образом, все что Вам нужно - подключиться раз в месяц к нашему сервису и получить обновленный ассортимент товаров.

1 стартмани

12.01.2015    35134    80    Sirruf    81    

Проверка контрагентов по ИНН и КПП через веб-сервис ФНС (внешняя)

Обработка справочников WEB v8 1cv8.cf Россия Абонемент ($m)

Обработка проверяет контрагентов по ИНН и КПП через веб-сервис ФНС на наличие регистрации в ЕГРН. Может выполняться в любых типовых конфигурациях, при наличии справочника "Контрагенты" и реквизитов "ИНН" и "КПП"

1 стартмани

25.12.2014    38011    129    Willforre    12    

Банк-Информ для 1С (8.3)

WEB v8 1cv8.cf Россия Абонемент ($m)

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

1 стартмани

05.11.2014    11119    4    ZOMI    5    

Загрузка курсов валют

Обработка справочников WEB v8 1cv8.cf Абонемент ($m)

Загрузка актуальных курсов валют с web - сервиса Сбербанка. На обычных и управляемых формах.

1 стартмани

15.10.2014    15979    18    miller-adm    3    

Маршруты в GoogleMaps для типовых конфигураций

Универсальные обработки WEB v8 1cv8.cf Абонемент ($m)

Данное решение позволяет проложить маршрут, используя GoogleMaps API без внесения изменений в конфигурацию

1 стартмани

21.08.2014    29474    96    RocKeR_13    13    

Загрузка документов из системы Emex через веб-сервисы (Коммерция-Автологистика)

Внешние источники данных WEB v8 v8::ОУ УТ10 УУ Абонемент ($m)

Обработка предназначенная для дилеров системы Emex, для загрузки документов из программы Коммерция(Автологистика) в 1С 8.2 Управление торговлей 10. Для загрузки используются веб-сервисы программы Автологистика.

10 стартмани

11.08.2014    19582    2    desarz    1    

Загрузка картинок для номенклатуры (google image API)

Обработка справочников WEB v8 1cv8.cf Абонемент ($m)

Обработка предназначена для поиска и загрузки картинок номенклатуры.

1 стартмани

04.06.2014    14498    34    OVladius    4    

Быстрый ввод контрагентов и организаций по данным ФНС

Обработка справочников WEB v8 КА1 БП2.0 УТ10 УПП1 УНФ Абонемент ($m)

Обработка для быстрого создания карточки контрагента/организации по данным ЕГРЮЛ/ЕГРИП.

1 стартмани

20.05.2014    40964    249    Sirruf    71    

Загрузка картинок с сайта из 1С (HTTPСоединение)

WEB v8 Абонемент ($m)

В этой статье я объясню как сохранять картинки сайта с помощью 1С. Для этого буду использовать встроенные объекты 1С (HTTPСоединение, HTTPЗапрос, HTTPОтвет).

1 стартмани

10.02.2014    46800    202    opx    25    

Менеджер по работе с Google календарем

Универсальные обработки WEB v8 v8::УФ УТ10 Розница ДО Абонемент ($m)

Обработка на управляемых формах для работы с календарями google, событиями календарей и контактами.

1 стартмани

06.02.2014    34575    112    sapervodichka    54    

Перенос данных Яндекс Маркет -> УТ11

WEB v8 УТ11 Абонемент ($m)

Внешняя обработка загрузки товаров из каталога Яндекс Маркет в УТ 11 (11.1.2.22 - 11.1.9.51)

1 стартмани

22.01.2014    17766    24    sdn-1    21    

Парсинг картинок с Лепры

WEB v8 1cv8.cf Абонемент ($m)

Модно нынче стало парсить сайты и качать картинки. Моя обработка ищет gif-ки на Лепре. Обработка предельно простая в изпользовании.

1 стартмани

12.09.2013    13869    3    kser87    8    

Внешняя печатная форма для проверки контрагентов с помощью Контур.Фокус

WEB v8 1cv8.cf Абонемент ($m)

Помогает быстро найти сведения по контрагенту: Реквизиты, информацию по учредителю, данные ЕГРЮЛ / ЕГРИП, запрос на выписку, финансовые данные, госконтракты, арбитражные дела, список связанных организаций

1 стартмани

17.03.2013    25580    63    kstukov    21    

Калькулятор стоимости доставки "Деловых линий"

Универсальные обработки WEB v8 1cv8.cf Абонемент ($m)

Калькулятор стоимости доставки "Деловых линий". Была поставлена задача интегрировать калькулятор в 1с.

1 стартмани

15.02.2013    13968    12    John_d    6    

Загрузка адресного классификатора в базу 1С теперь с сайта www.gnivc.ru

Универсальные обработки Обработка справочников WEB v8 Россия Абонемент ($m)

При помощи данной обработки Вы можете загрузить адресный классификатор "КЛАДР" с сайта www.gnivc.ru прямо в вашу базу 1С.

1 стартмани

21.10.2012    19022    10    dimabenyash    34    

Логистика (Распределение груза и прокладка оптимального маршрута с использованием API 2.0 Яндекс карт)

Универсальные обработки WEB Работа с интерфейсом v8 УТ10 Абонемент ($m)

Оптимизация транспортировки товара (нагрузка на транспорт и расстояние маршрута) от продавца к покупателю.

1 стартмани

30.09.2012    22350    53    cvmbackup    16    

Если шефу хочется секса – ему трудно отказать

Практика программирования Обработка документов Учет ТМЦ Учет ТМЦ v8 1cv8.cf Россия БУ Абонемент ($m)

Босс предлагает заняться сексом секретарше: - Светлана, у меня «встал один вопрос», может быть мы… «отчетик», у меня на столе, составим, м? - Извините, но у меня месячный «отчет»… Босс, в обломе уходит к себе в кабинет. Через 15 минут возвращается секретарша: - Владимир Сергеич, может быть Вам устно, ну или задним числом? - Нет, спасибо… я уже от руки набросал.

1 стартмани

26.04.2012    16203    0    director04    31