Перейти к основному содержимому

Описание HTTP методов

Пример описания метода в функциональном стиле:

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ОписаниеМетода("Получение данных из 1С")
		.ПараметрURL("Версия")
			.ОписаниеПараметра("Версия метода")
			.ЗначениеПеречисления("1.0")
			.ЗначениеПеречисления("2.0")
		.Ответ(200)
			.ОписаниеОтвета("Success")
	.Сформировать()
;

Наименование метода​

Наименование метода формируется по принципу:

Формирование наименования метода

Текстовое описание метода​

Основное описание (summary)​

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ОписаниеМетода("Получение данных из 1С")
	.Сформировать()
;

Дополнительное описание (description)​

к сведению

Данный функционал добавлен в версии 1.2.4.

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ДополнительноеОписаниеМетода("В дополнительном описании можно вставлять гиперссылки <a href=""http://example.com"">example.com</a>")
	.Сформировать()
;

Входящие параметры​

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

Параметры URL​

для URL /{Версия}/test

GET /1.0/test HTTP/1.1
Host: example.com
МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрURL("Версия")
	.Сформировать()
;

Параметры запроса​

GET /test?version=1.0 HTTP/1.1
Host: example.com
МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрЗапроса("version")
	.Сформировать()
;

Заголовки​

GET /test HTTP/1.1
Host: example.com
X-Api-Version: 1.0
МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрЗаголовка("X-Api-Version")
	.Сформировать()
;

Форму​

POST /test HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 11
version=1.0
МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйPOST")
		.ПараметрФормы("version")
	.Сформировать()
;

Дополнительные описания параметров​

Обязательный​

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрЗапроса("version")
		.Обязательный()
	.Сформировать()
;

Минимальная и максимальная длина​

к сведению

В swagger-ui информация о длине параметров не отображается. Зато в других интерфейсах (redoc, rapidoc, scalar и stoplight) корректно.

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрЗапроса("version")
		.МинимальнаяДлина(10)
		.МаксимальнаяДлина(255)
	.Сформировать()
;

Перечисление​

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		.ПараметрЗапроса("version")
		.ЗначениеПеречисления("1.0")
		.ЗначениеПеречисления("2.0")
	.Сформировать()
;

Передача в запрос тела запроса​

к сведению

Стандарт HTTP никак не регламентирует передачу тела запроса в зависимости от метода. Но скорее всего при методе GET web-сервер проигнорирует переданное тело.

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйPOST")
		.ОписаниеМетода("Отправка данных в 1С")
		.Тело()
			.ТипТела("application/json")
				.СхемаТела("ТестовыйОбъект")
	.Сформировать()
;

Исходящие данные​

Данные возвращаемые HTTP-сервисом формируются из комбинации кода ответа, MIME-типа и описания возвращаемого объекта или массива.

МассивОписанийМетодов = Swag_Описание
	.Метод("ТестовыйGET")
		// Код ответа
		.Ответ(200)
			.ОписаниеОтвета("Success")
			// MIME-тип ответа
			.ТипОтвета("application/json")
				// Схема объекта в ответе
				.СхемаОтвета("ТестовыйОбъект")
	.Сформировать()
;