Описание объектов

Общий пример

Методы HTTP-сервисов принимают и/или возвращают объекты или массивы объектов. Каждый объект содержит в себе поля. Описания объектов предназначены для того чтобы зафиксировать в документации состав, типы, описания и другие параметры этих полей.

В общем случае объект в функциональном стиле можно описать так:

Объекты = Swag_Описание
	.Объект("ОбъектПартнер")
		.ОписаниеОбъекта("Объект для передачи данных о покупателе или поставщике")
		.Свойство("Идентификатор")
			.ОписаниеСвойства("Идентификатор партнера из 1С")
			.ТипЗначения("string")
			.Пример("a188a1a4-32fd-4d9e-a54c-89939b7bfdf6")
		.Свойство("Наименование")
			.ТипЗначения("string")
			.Пример("ООО ""СтройТехМонтаж""")
		.Свойство("ЭтоПокупатель")
			.ТипЗначения("boolean")
			.Пример(Истина)
		.Свойство("ОсновнойДоговор")
			.ТипЗначения("object")
			.Схема("ОбъектДоговор")
		.Свойство("Адреса")
			.ТипЗначения("array")
			.Схема("ОбъектАдрес")
	//
	.Объект("ОбъектДоговор")
		.Свойство("Идентификатор")
			.ОписаниеСвойства("Идентификатор договора из 1С")
			.ТипЗначения("string")
			.Пример("8f80d9d3-730a-4b8f-82a5-4ff52960691e")
		.Свойство("Номер")
			.ОписаниеСвойства("Номер договора")
			.ТипЗначения("string")
			.Пример("00УТ-007645")
	//
	.Объект("ОбъектАдрес")
		.Свойство("Адрес")
			.ОписаниеСвойства("Адрес строкой")
			.ТипЗначения("string")
			.Пример("Москва, Ленинский проспект, дом 4, строение 1А, квартира 10")
	.Сформировать()
;

результат подобного описания будет такой:

{
  "Идентификатор": "a188a1a4-32fd-4d9e-a54c-89939b7bfdf6",
  "Наименование": "ООО \"СтройТехМонтаж\"",
  "ЭтоПокупатель": true,
  "ОсновнойДоговор": {
    "Идентификатор": "8f80d9d3-730a-4b8f-82a5-4ff52960691e",
    "Номер": "00УТ-007645"
  },
  "Адреса": [
    {
      "Адрес": "Москва, Ленинский проспект, дом 4, строение 1А, квартира 10"
    }
  ]
}

В данном примере было создано три объекта: ОбъектПартнер, ОбъектДоговор и ОбъектАдрес. Последние два были использованы при описании объекта ОбъектПартнер.

warning

В версии 1.2.7 метод "Описание" был признан устаревшим. Вместо него следует использовать метод "ОписаниеСвойства". Метод "Описание" будет окончательно удален в версии 1.3

к сведению

Метод "ОписаниеОбъекта" добавлен в версии 1.2.7.

Другие возможные модификаторы объектов и свойств

Объекты = Swag_Описание
	.Объект("ОбъектПартнер")
		.ОписаниеОбъекта("Объект для передачи данных о покупателе или поставщике")
		.ОбязательныеПоля("Наименование, СуммаПродаж")
		.Свойство("Наименование")
			.ТипЗначения("string")
			.Пример("ООО ""СтройТехМонтаж""")
			.МинимальнаяДлина(1)
			.МаксимальнаяДлина(255)
		.Свойство("СуммаПродаж")
			.ТипЗначения("integer")
			.Пример(123.45)
			.Обязательный()
			.ФорматЗначения("int64")
			.Минимум(10)
			.Максимум(1000)
			.НеВключаяМинимум()
			.НеВключаяМаксимум()
			.ПоУмолчанию(20)
	.Сформировать()
;

Особенность использования методов ОписаниеОбъекта и ОписаниеСвойства

Некоторые движки (в частности swagger-ui и ReDoc) не отображают описание свойства для поля типа "object". Описание для таких случаев они берут из описания самого объекта. Например:

Объекты = Swag_Описание
	.Объект("ОбъектПартнер")
		.Свойство("ОсновнойДоговор")
			// Это описание не будет отображено
			.ОписаниеСвойства("Основной договор с партнером")
			.ТипЗначения("object")
			.Схема("ОбъектДоговор")
	//
	.Объект("ОбъектДоговор")
		// В объекте "ОбъектПартнер" для поля "ОсновнойДоговор" будет показан текст из строки ниже
		.ОписаниеОбъекта("Договор с партнером")
		.Свойство("Идентификатор")
			.ОписаниеСвойства("Идентификатор договора из 1С")
			.ТипЗначения("string")
			.Пример("8f80d9d3-730a-4b8f-82a5-4ff52960691e")
		.Свойство("Номер")
			.ОписаниеСвойства("Номер договора")
			.ТипЗначения("string")
			.Пример("00УТ-007645")
	.Сформировать()
;

Комбинирование (объединение) типов данных в полях объекта

Объекты = Swag_Описание
	.Объект("КонтактнаяИнформация")
		.Свойство("Данные")
			.ТипЗначения("object")
			.ОбъединениеСхем("oneOf")
				.Схема("ОбъектПочтовыйАдрес")
				.Схема("ОбъектТелефон")
				.Схема("ОбъектЭлектроннаяПочта")
	//
	.Объект("ОбъектПочтовыйАдрес")
		.Свойство("Индекс")
			.ТипЗначения("string")
		.Свойство("Город")
			.ТипЗначения("string")
		.Свойство("Улица")
			.ТипЗначения("string")
	//
	.Объект("ОбъектТелефон")
		.Свойство("КодСтраны")
			.ТипЗначения("string")
		.Свойство("Код")
			.ТипЗначения("string")
		.Свойство("Телефон")
			.ТипЗначения("string")
	//
	.Объект("ОбъектЭлектроннаяПочта")
		.Свойство("АдресЭлектроннойПочты")
			.ТипЗначения("string")
	.Сформировать()
;