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

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

См. также

Универсальная выгрузка/загрузка данных для отличающихся конфигураций (JSON, Такси+ОФ) Промо

Перенос данных из 1C8 в 1C8 Универсальные обработки Распределенная БД (УРИБ, УРБД) v8 1cv8.cf Абонемент ($m)

Простой перенос через JSON данных между двумя базами 1С (документов, справочников, ПВХ, ПВР, счетов). Аналогична произвольной выгрузке в типовой "Выгрузка/загрузка XML", но может использоваться для отличающихся конфигураций. Подходит для любых пар баз с любым интерфейсом (управляемый + обычный). Без настроек. Не требует идентичности конфигураций и платформ. При переносе типы данных сопоставляются по наименованиям метаданных, объекты и ссылки по UID.

1 стартмани

22.10.2014    202074    3077    ekaruk    178    

Загрузка данных из 1С МиниДеньги в 1С:Деньги 8, редакция 2.0

Обмен через XML Перенос данных из 1C8 в 1C8 v8 Домашние учет и финансы УУ Абонемент ($m)

Обработка для первоначальной загрузки данных (справочников и операций) в настольную программу 1С:Деньги 8, редакция 2.0 из файлы резервной копии мобильной программы 1С Миниденьги.

2 стартмани

01.10.2015    14827    14    Claus32    5    

Редактор чеков ККМ Розница 2.0 - 2.3

Обработка документов Кассовые операции Розничная торговля Кассовые операции Розничная торговля v8 Розница Розничная и сетевая торговля (FMCG) Рестораны, кафе и фаст-фуд БУ НУ Абонемент ($m)

Обработка чеков ККМ списком (редактирование, удаление, ...). Переформирование ОРП, связь чеков с ОРП. Редактирование времени КС. Редактирование суммы и времени выемки.

1 стартмани

06.08.2015    47858    450    Dima_    83    

Загрузка из Excel в 1С:Розница

Обработка документов Обработка справочников Загрузка и выгрузка в Excel Учет ТМЦ Учет ТМЦ v8 Розница Россия УУ Абонемент ($m)

Универсальная загрузка Excel файлов в 1С:Розница 2.0

1 стартмани

27.05.2015    14610    90    KarinaSV    7    

Автоматическая установка себестоимости номенклатуры для конфигурации Розница 2.0 (2.1) +Бонус, исправляем ошибки при настройке расписания запуска для внешних обработок в Рознице 2.0

Ценообразование, прайсы Обработка документов Розничная торговля Ценообразование, анализ цен Розничная торговля Ценообразование, анализ цен v8 Розница Розничная и сетевая торговля (FMCG) Россия УУ Абонемент ($m)

Обработка для автоматического создания документов Установка себестоимости, в случае если себестоимость не установлена на момент продажи. Помогает упростить установку себестоимости номенклатуры, если у вас в базе ведется учет по нескольким магазинам. Тестировалась на релизе 2.0.8.12 и 2.1.7.14. Подойдет для тех систем, где себестоимость номенклатуры одинакова для всех магазинов.

1 стартмани

31.03.2014    26193    38    sanches    15    

Выемка денежных средств из КассыККМ. Розница 2.0

Кассовые операции ККМ Кассовые операции v8 Розница УУ Абонемент ($m)

Уставшим от отсутствия ВыемкиДС после закрытия кассовой смены посвящается. Подключаемая обработка. Управляемый интерфейс.

1 стартмани

12.12.2012    74953    287    StepByStep    40