Swagger в 1С: от настройки до публикации

•  Что такое swagger и зачем он нужен в 1С

Swagger (ныне OpenAPI) — это набор инструментов для проектирования, документирования и тестирования RESTful API.

Зачем Swagger в 1С?

Стандартизация API       – все методы и структуры данных описаны в едином формате.
Удобство тестирования  – можно отправлять запросы прямо из браузера.
Автодокументирование  – не нужно писать документацию вручную.
Упрощение интеграции  – внешние системы могут сразу видеть, как работать с API.

Концепция решения

На решение значительное влияние оказала библиотека swaggo

1. В строго определенном синтаксисе формируем комментарии к обработчикам методов http сервисов.

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

Для того, чтобы облегчить написание комментариев для их создания, прилагается специальная обработка, работа с которой описана ниже.

// @Tags		MDM
// @Summary		MDM (Products GET)
// @Description		MDM (Products GET)
// @Router	/mdm/* [GET]
// @Produce json
// @Accept	json
// @Param		name		query		string		false		"поиск по наименованию"
// <value>
// tele
// </value>
// @Success		200		{array}	array		"ок"
// <value>
// [{"id":1,"name":"Смартфон XYZ","price":599.99},{"id":2,"name":"Ноутбук ABC","price":1299.99}]
// </value>
Функция productsGET(Запрос)  	

	Возврат ОбработчикHTTP.ПолучитьОтвет(Запрос, "GET mdm/products" , "Products.productsGET");

КонецФункции

2. Выгружаем конфигурацию в файлы и преобразовываем комментарии к файлу Swagger.JSON

{
"openapi": "3.0.3",
"info": {
"description": "Products demo API",
"title": "API Server for Products demo",
"version": "1.0"
},
"servers": [
{
"url": "http://host/hs#"
}
],
"paths": {
"/mdm/*": {
"get": {
"parameters": [
{
"description": "поиск по наименованию",
"name": "name",
"in": "query",
....
}

3. Полученный файл публикуем через http сервис (в макете находится готовая react сборка клиента Swagger)

Функция SwagerGET(Запрос)
	
	Ответ = Новый HTTPСервисОтвет(200);
	Ответ.Заголовки.Вставить("Content-Type","text/html; charset=utf-8");
	HTMLSwaggerClient = ПолучитьОбщийМакет("swSwaggerClient").ПолучитьТекст();	
	HTMLSwaggerClient = СтрЗаменить(HTMLSwaggerClient, "#host", ПолучитьБазовыйURL(Запрос.БазовыйURL));  
	Ответ.Заголовки.Вставить("Content-Type","text/html; charset=utf-8");
	Ответ.УстановитьТелоИзСтроки(HTMLSwaggerClient, "UTF-8");   
	Возврат Ответ;

КонецФункции

Описание тегов нотаций
 

@Tags        MDM

Определяет группу, в которую входит сервис

@Summary     MDM (Products GET)

Наименование сервиса

@Description        Назначение роли пользователю

@Router    /mdm/* [GET]
Определяет url и http метод
@Produce  json
@Accept    json

Определяют mame MIME-типы (пока у нас поддерживается только json )

@Param        Input        body        object        true        "Input"

Определяет входящий параметр (их может быть несколько)

1. Имя - Input       
2. Размещение - body (возможны следующие значения header - параметр в заголовке, query- параметр в строке например ?pageId=438738746,  body-в теле запроса, path- в url сервиса http:localhost/{region}/work )       
3. Тип данных - object    (возможны следующие типы number, boolean, object, string, array) 
4. Обязательный параметр -  true       
5. Имя параметра - "Input"

После тега обязательно должно быть определено возможное значение параметра
 

// <value>
// tele
// </value>

@Success        200        {string}    string "ОК"

Определяет "положительный ответ" (тегов может быть несколько но у них должен быть уникальный http код ответа)

1. Код ответа - 200
2.  {string}  - тип сваггер
3. string  - тип системы источника
4. "ОК" - комментарий

После тега обязательно должно быть определено возможное значение параметра

// <value>
// [{"id":1,"name":"Смартфон XYZ","price":599.99},{"id":2,"name":"Ноутбук ABC","price":1299.99}]
// </value>

@Failure        400        {string}    string "Не верный параметры ответа"

Определяет "отрицательный ответ" (тегов может быть несколько, но у них должен быть уникальный http код ответа)

1. Код ответа - 400
2.  {string}  - тип сваггер
3. string  - тип системы источника
4. "ОК" - комментарий

После тега обязательно должно быть определено возможное значение параметра
 

<value>  
    "Не заполнено значение строки поиска"
</value>

Обработка "Генерация swagger"

Обработка предназначена для автоматического создания и редактирования нотаций, а также просмотра и формирования файла Swagger.JSON

Инструкция по формированию нотаций

1. Выбираем описываемый сервис и метод

  2. Заполняем параметры запроса

 
В случае некорректного заполнения обработка выведет ошибку

Для заполнения значения в редакторе json нужно нажать на кнопку открытия

3. Заполняем результаты запроса 

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

Для того, чтобы запрос выполнился, необходимо заполнить параметры соединения по кнопке.

4.  В случае необходимости, если сервис устанавливает какие-либо параметры в заголовке ответа, есть возможность указать их в соответствующей табличной части.

5. В сценарии редактирование ранее созданных нотаций имеется возможность заполнить обработку по нотациям.

6. Полученную нотацию вставляем комментарием в код обработчика запроса

Инструкция по сборке публикуемого Swagger.json

1. Выгружаем конфигурацию в файлы.
2. Запускаем обработку, выбираем путь к каталогу проекта 1с и нажимаем кнопку "Сгенерировать Swagger JSON"

3. Копируем полученный Swagger.json в макет 

4. Смотрим полученный результат.

Для просмотра надо открыть опубликованный сервис базы, например: https://server/test/hs/swagger