Прежде чем мы перейдем к руководству OpenAPI, Обратим внимание на YAML, чтобы лучше его понять, так как это наиболее распространенный синтаксис для документа спецификации OpenAPI. Можно использовать и JSON, но преобладающей тенденцией в документации OpenAPI является формат YAML.)
У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки < или >. Вместо этого он использует двоеточия для обозначения свойств объекта и дефисы для обозначения массива.
С YAML легче работать, потому что он удаляет скобки запятые, которые мешают чтению контента.
Сам сайт YAML написан с использованием YAML, который, как можно сразу увидеть, не предназначен для кодирования веб-страниц.
YAML - это попытка создать более удобный для восприятия формат обмена данными. Он похож на JSON (который на самом деле является подмножеством YAML), но использует пробелы, двоеточия и дефисы для обозначения структуры.
Многие компьютеры принимают данные в формате YAML или JSON. Этот синтаксис обычно используется в файлах конфигурации и во все большем количестве платформ (например, Jekyll), поэтому рекомендуется его знать.
В большинстве случаев YAML и JSON - это разные способы структурирования одних и тех же данных. Точечная запись обращается к значениям так же. Например, пользовательский интерфейс Swagger может эквивалентно читать файлы openapi.json или openapi.yaml. Практически любой парсер (анализатор), который читает JSON, также будет читать YAML. Однако некоторые парсеры JSON могут не читать YAML, потому что в YAML есть несколько функций, которых нет в JSON (подробнее об этом ниже).
В синтаксисе YAML значительным является интервал. Каждый отступ с двумя пробелами представляет новый уровень:
level1:
level2:
Level3:
Каждый новый уровень - это объект. В этом примере объект level1 содержит объект level2, который содержит объект level3.
В YAML обычно используется клавиша
Tab(так как интервал между вкладками нестандартен). Вместо этого дважды нажимается пробел.
Каждый уровень может содержать либо одну пару ключ-значение (также называемую словарём в жаргоне YAML), либо последовательность (список дефисов):
level3:
-
itema: "one"
itemameta: "two"
-
itemb: "three"
itembmeta: "four"
Значения для каждого ключа могут быть заключены в кавычки. Если в значении есть двоеточие или кавычка, нужно заключить его в кавычки.
Ранее в курсе мы рассмотрели различные структуры JSON, включающие объекты и массивы. Теперь посмотрим на эквивалент синтаксиса YAML для каждого из этих же объектов JSON.
Можно использовать Unserialize.me для преобразования из JSON в YAML или из YAML в JSON.
Вот пара ключ-значение в json
{
"key1":"value1",
"key2":"value2"
}
Вот та же пара в YAML
key1: value1
key2: value2
Вот массив (список элементов) в JSON:
["first", "second", "third"]
В YAML массив форматируется в список с дефисами:
- first
- second
- third
Вот объект, содержащий массив в JSON:
{
"children": ["Avery","Callie","Lucy","Molly"],
"hobbies":["swimming","biking","drawing","horseplaying]
}
Тот же объект с массивом в YAML:
children:
- Avery
- Callie
- Lucy
- Molly
hobbies:
- swimming
- biking
- drawing
- horseplaying
Массив, содержащий объект в JSON:
[
{
"name":"Tom",
"age":43
},
{
"name":"Shannon",
"age":41
}
]
Тот же массив с объектом в YAML:
-
name: Tom
age: 42
-
name: Shannon
age: 41
Сравнение двух форматов покажет что общего в YAML и JSON. Синтаксис YAML более читабелен? В этих простых примерах трудно увидеть , но в целом это так.
В JavaScript для доступа к значениям в YAML используются те же методы точечной нотации, что и в JSON. (Это в значительной степени взаимозаменяемые форматы.) Однако преимущество использования YAML заключается в том, что он более читабелен, чем JSON.
Но и YAML может быть более сложным, все зависит от правильного расстановки пробелов. Иногда количество пробелов трудно увидеть (особенно со сложной структурой), и в таких вариантах JSON (хотя может быть более громоздким), подойдет больше.
YAML имеет некоторые особенности, отсутствующие в JSON. В YAML-файлах можно комментировать строки, используя знак #. YAML также позволяет использовать то, что называется «якоря». Например, предположим, есть два схожих определения. Можно написать определение один раз и использовать указатель для ссылки на оба:
api: &apidef Application programming interface
application_programming_interface: *apidef
Если вы обратитесь к значению, для обоих будет использоваться одно и то же определение. *Apidef действует как якорь или указатель на определение, установленное в &apidef
В руководстве по OpenAPI не будем использовать эти уникальные функции YAML, но их стоит отметить, поскольку JSON и YAML не совсем эквивалентны. Подробнее о других различиях между JSON и YAML см. В разделе «Изучение YAML за несколько минут». Чтобы узнать больше о YAML, можно посмотреть справочник YAML.
YAML также используется в Jekyll. Можно изучить учебник автора по YAML в контексте Jekyll для более подробной информации.