Работа в YAML

Прежде чем мы перейдем к руководству OpenAPI, Обратим внимание на YAML, чтобы лучше его понять, так как это наиболее распространенный синтаксис для документа спецификации OpenAPI. Можно использовать и JSON, но преобладающей тенденцией в документации OpenAPI является формат YAML.)

У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки < или >. Вместо этого он использует двоеточия для обозначения свойств объекта и дефисы для обозначения массива.

Работа с YAML

С YAML легче работать, потому что он удаляет скобки запятые, которые мешают чтению контента.

YAML - это попытка создать более удобный для восприятия формат обмена данными. Он похож на JSON (который на самом деле является подмножеством YAML), но использует пробелы, двоеточия и дефисы для обозначения структуры.

Многие компьютеры принимают данные в формате YAML или JSON. Этот синтаксис обычно используется в файлах конфигурации и во все большем количестве платформ (например, Jekyll), поэтому рекомендуется его знать.

YAML - это расширенный JSON

В большинстве случаев YAML и JSON - это разные способы структурирования одних и тех же данных. Точечная запись обращается к значениям так же. Например, пользовательский интерфейс Swagger может эквивалентно читать файлы openapi.json или openapi.yaml. Практически любой парсер (анализатор), который читает JSON, также будет читать YAML. Однако некоторые парсеры JSON могут не читать YAML, потому что в YAML есть несколько функций, которых нет в JSON (подробнее об этом ниже).

Синтаксис YAML

В синтаксисе YAML значительным является интервал. Каждый отступ с двумя пробелами представляет новый уровень:

level1:
  level2:
    Level3:

Каждый новый уровень - это объект. В этом примере объект level1 содержит объект level2, который содержит объект level3.

Каждый уровень может содержать либо одну пару ключ-значение (также называемую словарём в жаргоне YAML), либо последовательность (список дефисов):

level3:
  -
    itema: "one"
    itemameta: "two"
  -
    itemb: "three"
    itembmeta: "four"

Значения для каждого ключа могут быть заключены в кавычки. Если в значении есть двоеточие или кавычка, нужно заключить его в кавычки.

Сравнение YAML и JSON

Ранее в курсе мы рассмотрели различные структуры JSON, включающие объекты и массивы. Теперь посмотрим на эквивалент синтаксиса 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 имеет некоторые особенности, отсутствующие в 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 для более подробной информации.

🔙

Go next ➡