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