YAML для написания
Длинные описания лучше читаются в блочном тексте YAML, а комментарии позволяют оставлять пояснения для ревьюеров.
Конвертируйте спецификации API между JSON и YAML, не ломая пути $ref и коды ответов.
Каждая строка результата в стандартном форматировании рядом с путём к значению, которое она содержит. Нажмите на строку, чтобы скопировать путь.
Работает полностью в вашем браузере: ничего не загружается на сервер. Действуют ограничения добросовестного использования (5 MB на ввод, лимит частоты конвертаций) для защиты от спама и ботов.
Две детали ломают спецификации, сконвертированные вручную: #, с которого начинается комментарий YAML, и коды статусов, которые становятся целыми числами. Конвертер учитывает обе.
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} paths:
/pets/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4XX:
description: Client error Переключитесь на Вручную, без кавычек, чтобы увидеть, как $ref превращается в null, а хост с подстановочным знаком не разбирается.
После конвертации запустите линтер, чтобы проверить саму спецификацию, а не только синтаксис. Здесь каждая локальная $ref проверяется по мере редактирования.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Длинные описания лучше читаются в блочном тексте YAML, а комментарии позволяют оставлять пояснения для ревьюеров.
Генераторы кода, шлюзы и SDK часто быстрее всего загружают JSON, и многие отдают спецификацию по адресу /openapi.json.
Оба формата описывают один и тот же API. Конвертируйте свободно в любом направлении: из спецификации ничего не теряется.
Конвертеры, валидаторы и пошаговые руководства для всех мест, где встречаются JSON и YAML.
Вставьте или загрузите openapi.json и скопируйте YAML из правой панели или скачайте его как openapi.yaml. Структура, указатели $ref, примеры и описания сохраняются в точности.
Да. Конвертер работает со структурой документа, поэтому спецификации Swagger 2.0, OpenAPI 3.0 и OpenAPI 3.1 конвертируются одинаково, в обоих направлениях.
В YAML # начинает комментарий, если стоит после пробела. Без кавычек всё после $ref: считалось бы комментарием, и ссылка оказалась бы пустой. Конвертер заключает её в кавычки автоматически.
OpenAPI требует, чтобы коды ответов были строковыми ключами. 200 без кавычек в YAML является целым числом; большинство инструментов это принимает, но строгие валидаторы нет. Кавычки сохраняют спецификацию корректной везде.
Переключите направление на YAML → JSON переключателем над редактором или воспользуйтесь конвертером YAML в JSON. Якоря в YAML разворачиваются, поскольку в JSON нет ссылок такого рода.