Зачем это надо
- Убрать разрыв между написанием кода и подготовкой документации
- Всегда соответствующие документации сервисы
- Унифицированный контроль соответствия поступивших запросов спецификации
- Возможность унифицированного контроля формируемых ответов спецификации
- Онлайн документацию формата Swagger UI средствами самого 1С сервиса без внешних зависимостей
- Разделение этапов разработки интерфейса и реализации функционала
- Выделение конечного функционала по обработкам
- Возможность назначения обработчиков конечных точек сервиса в режиме предприятия
- Возможность создавать в конечных обработчиках "долгоживущие" объекты
Требования
1С Предприятие версии >= 8.3.9
Установка
- Скачать последнюю стабильную версию
- Установить расширения в порядке номеров
- Для установленных расширений снять флаги "Безопасный режим" и "Защита от опасных действий"
Использование
Простейшая конфигурация HTTP сервиса в конфигурации/расширении (нового)
В общем случае требуется один ресурс с шаблоном /*
и одной конечной точкой, обрабатывающей все http-методы
Обработчик входящего запроса состоит из единственного вызова
Возврат оас_Сервис.Ответ(Запрос);
Разрабатываем спецификацию сервиса в формате OpenAPI v3.x, сохраняем в формате JSON
Возможно используя визуальный редактор
- stoplight - показался наиболее функциональным и дружелюбным, есть бесплатный тариф
- mermade - полностью бесплатный, но не такой удобный как stoplight
Настройка сервиса в обработке "ОАС. Управление сервисами"
(на скриншоте отмечены номера пунктов в интерфейсе)
- Выбрать HTTP-сервис
- Загрузить спецификацию в 1С
- Получаем шаблон модуля обработки, вызываемой при получении запросов к выбранной точке
- Создаем обработку в конфигурации или расширении
- Копируем текст шаблона в модуль объекта созданной обработки, реализуем функционал
- Выбираем созданную обработку как обработчик запросов конечной точки сервиса
Повторяем пункты 3-5 для каждой конечной точки.
Шаблон модуля обработки (4) содержит комментарии, содержащие информацию о спецификации конечной точки
- Имена сервиса, конечной точки, HTTP метода
- Параметры, их обязательность
- Тип тела запроса, его обязательность, при наличии в спецификации схема содержания
- Схема тела ответа по спецификации
Автоматически формируемая сервисом документация
Тема "Просмотр"
Тема "Чтение"