Swagger для 1С:Предприятия 8

Особенности/отличия в "fork by Kyrales" https://github.com/Kyrales/swagger-1c

Цель: Возможность полноценно использовать в крупных компаниях с учетом основных возможностей OpenAPI

Последняя версия расширения собирается из Develop из папки .\src\cfe\swagger\

• Добавлен модуль Swag_НастройкиSwaggerПереопределяемый. Настройки для базовых адресов HTTP-серверов, которые можно настроить в Swag_НастройкиSwaggerПереопределяемый.БазовыеАдресаHttpСерверов1С(). Удобно формировать Swagger сразу со списком реальных адресов для тестирования и прода
• Добавлен модуль Swag_ОбщиеОписанияПереопределяемый. Необходимо для возможности задавать описания общих унифицированных описаний объектов. Например по ответам: 400, 404, 422 и др.
• Добавлен функционал описания массива строк и чисел (zerobig#27) Например:

- Добавлен шаблон разработчика [ШаблонРазработчикаSwagger.st](ШаблонРазработчикаSwagger.st). Для возможности быстрого создания методов и описаний объектов - Добавлена обработка Swag_ПолучитьТекстДляSwagger. Для получения текста json сваггера из 1С. - Добавлена обработка Swag_СозданиеПользователяSwagger. Для быстрого создания пользователя, который может открыть swagger ссылку - это удобно использовать на разработческих базах, если нужно быстро расшарить ссылку на Swagger тем пользователям у которых нет доступа по-умолчанию к этой базе (например смежным кросс-командам) - При формировании Swagger-описания вывод в версии текущей даты формирования. Удобно для публикаций на выделенный сервер уже готового согласованного json описания - можем понять когда было сделано обновление. - Незначительный рефакторинг модулей под стандарты 1С

Тестовая база

Тестирование проводится на базе Демонстрационная конфигурация "Библиотека стандартных подсистем"

Базовое Readme из https://github.com/zerobig/swagger-1c

Данный продукт предназначен для организации процесса документирования HTTP сервисов конфигураций написанных на платформе 1С:Предприятие.

Кроме swagger-ui для визуализации API могут использоваться следующие решения:

ReDoc

Scalar

Stoplight

RapiDoc

Для того чтобы переключиться на желаемую библиотеку в строке запроса надо добавить параметр:

/swagger/index.html?ui=scalar

Состав репозитория

• swagger - расширение конфигурации реализующее функциональность создания документации
• swagger-test - расширение для тестирования

Порядок установки

В режиме конфигуратора создать расширение и выполнить загрузку конфигурации из файлов, указав при этом каталог swagger.

Документация

Документация находится по адресу https://zerobig.github.io/swagger-1c/. Наполнение продолжается.

Запуск

Опубликовать базу 1С:Предприятия на web-сервере. Обязательно проконтролировать, что cтоит настройка публикации "Публиковать HTTP сервисы расширений по умолчанию". Возможно после публикации или изменения настроек публикации потребуется перезапуск web-сервера. Открыть в браузере страницу http://<Адрес_опубликованной_базы_1С_Предприятия>/hs/swagger/index.html

Создание описаний для своих HTTP сервисов

Поиск описаний происходит среди общих модулей. Наименование общего модуля должно быть построено по шаблону: "<Наименование_HTTP_сервиса>Описание".

Пример создания описания можно посмотреть:

• swagger-test\CommonModules\SwagTest_Тестовый_HTTPСервисОписание
• swagger-test\CommonModules\ПередачаДанныхОписание

Проверка входящих (запросов) и исходящих (ответов)

Реализовано через вызов обёрток "ПроверитьПараметры" и "ПроверитьОтвет" соответственно.

Для проверки входящих параметров:

РезультатПроверкиПараметров = Swag_ОбработкаHTTP.ПроверитьПараметры("SwagTest_Тестовый_HTTPСервис", "ТестовыйGET", Запрос);
Если Не ПустаяСтрока(РезультатПроверкиПараметров) Тогда
    Возврат Swag_ОбработкаHTTP.ПолучитьОтветОшибки(РезультатПроверкиПараметров, Истина);
КонецЕсли;

Для проверки ответа:

Возврат Swag_ОбработкаHTTP.ПроверитьОтвет("SwagTest_Тестовый_HTTPСервис", "ТестовыйGET", Ответ);

Функциональность	Статус	Обсуждение
Наличие описания в запросах	Запланировано
Входящие параметры GET запросов	Запланировано
Входящие параметры POST запросов	Запланировано
Наличие описания в ответах	Реализовано
Наличие и соответствие кода ответа	Реализовано
Наличие и соответствие типа MIME в ответе	Реализовано
Исходящие параметры	Запланировано
Статический swagger.json	В работе	Ссылка