OpenAPI и Swagger: JSON към YAML

Конвертирайте API спецификации между JSON и YAML, без да чупите пътищата в $ref или кодовете на отговорите.

Опции за изхода

JSONвход

Празно

YAMLизход

Изходът YAML се появява тук

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

Зареждане от URL

Файлът се изтегля директно от вашия браузър, затова сървърът трябва да разрешава заявки от друг произход (cross-origin).

Клавишни комбинации

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 няма препратки от този вид.