OpenAPI и Swagger: JSON в YAML

Конвертируйте спецификации API между JSON и YAML, не ломая пути $ref и коды ответов.

Параметры вывода

JSONввод

Пусто

YAMLвывод

Здесь появится вывод YAML

Работает полностью в вашем браузере: ничего не загружается на сервер. Действуют ограничения добросовестного использования (5 MB на ввод, лимит частоты конвертаций) для защиты от спама и ботов.

Загрузка по URL

Файл запрашивается напрямую вашим браузером, поэтому сервер должен разрешать кросс-доменные запросы.

Сочетания клавиш

Ctrl / ⌘ + Enter Конвертировать сейчас
Ctrl / ⌘ + S Скачать вывод
Alt + Shift + C Копировать вывод
Alt + Shift + F Исправить и отформатировать входной JSON
Alt + Shift + S Поменять направление
Alt + Shift + T Переключение между видами: код, дерево и карта
Ctrl / ⌘ + Z Отменить, в том числе «Формат», «Исправить» и «Очистить»
Esc Выйти из полноэкранного режима
Размер текста в редакторе

Указатели $ref и коды ответов остаются корректными

Две детали ломают спецификации, сконвертированные вручную: #, с которого начинается комментарий YAML, и коды статусов, которые становятся целыми числами. Конвертер учитывает обе.

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
paths:
  /pets/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4XX:
          description: Client error

Переключитесь на Вручную, без кавычек, чтобы увидеть, как $ref превращается в null, а хост с подстановочным знаком не разбирается.

Проверьте результат линтером

После конвертации запустите линтер, чтобы проверить саму спецификацию, а не только синтаксис. Здесь каждая локальная $ref проверяется по мере редактирования.

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

JSON или YAML для спецификаций API?

YAML для написания

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

JSON для инструментов

Генераторы кода, шлюзы и SDK часто быстрее всего загружают JSON, и многие отдают спецификацию по адресу /openapi.json.

Один и тот же документ

Оба формата описывают один и тот же API. Конвертируйте свободно в любом направлении: из спецификации ничего не теряется.

Другие инструменты

Конвертеры, валидаторы и пошаговые руководства для всех мест, где встречаются JSON и YAML.

Частые вопросы

Как конвертировать файл OpenAPI JSON в YAML?

Вставьте или загрузите openapi.json и скопируйте YAML из правой панели или скачайте его как openapi.yaml. Структура, указатели $ref, примеры и описания сохраняются в точности.

Работает ли это для Swagger 2.0, а не только для OpenAPI 3?

Да. Конвертер работает со структурой документа, поэтому спецификации Swagger 2.0, OpenAPI 3.0 и OpenAPI 3.1 конвертируются одинаково, в обоих направлениях.

Почему $ref: '#/components/...' в кавычках?

В YAML # начинает комментарий, если стоит после пробела. Без кавычек всё после $ref: считалось бы комментарием, и ссылка оказалась бы пустой. Конвертер заключает её в кавычки автоматически.

Почему коды ответов записаны как '200'?

OpenAPI требует, чтобы коды ответов были строковыми ключами. 200 без кавычек в YAML является целым числом; большинство инструментов это принимает, но строгие валидаторы нет. Кавычки сохраняют спецификацию корректной везде.

Как конвертировать OpenAPI YAML обратно в JSON?

Переключите направление на YAML → JSON переключателем над редактором или воспользуйтесь конвертером YAML в JSON. Якоря в YAML разворачиваются, поскольку в JSON нет ссылок такого рода.