OpenAPI i Swagger z JSON na YAML

Konwertuj specyfikacje API między JSON a YAML bez psucia ścieżek $ref i kodów odpowiedzi.

Opcje wyniku

JSONwejście

Pusto

YAMLwynik

Tutaj pojawi się wynik YAML

Działa w całości w przeglądarce: nic nie jest przesyłane. Obowiązują limity uczciwego użytkowania (5 MB na dane wejściowe, ograniczona liczba konwersji), aby zapobiegać spamowi i botom.

Wczytaj z adresu URL

Plik jest pobierany bezpośrednio przez przeglądarkę, więc serwer musi zezwalać na żądania cross-origin.

Skróty klawiszowe

Ctrl / ⌘ + Enter Konwertuj teraz
Ctrl / ⌘ + S Pobierz wynik
Alt + Shift + C Kopiuj wynik
Alt + Shift + F Napraw i sformatuj wejściowy JSON
Alt + Shift + S Zamień kierunek
Alt + Shift + T Przełączaj widoki: kod, drzewo i mapa
Ctrl / ⌘ + Z Cofnij, także po użyciu Formatuj, Napraw i Wyczyść
Esc Wyjdź z pełnego ekranu
Rozmiar tekstu w edytorze

Wskaźniki $ref i kody odpowiedzi pozostają poprawne

Dwa szczegóły psują ręcznie konwertowane specyfikacje: znak #, który rozpoczyna komentarz YAML, oraz kody statusu, które stają się liczbami całkowitymi. Oba są obsługiwane.

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

Przełącz na Ręcznie, bez cudzysłowów, aby zobaczyć, jak $ref zmienia się w null, a host z symbolem wieloznacznym nie przechodzi parsowania.

Sprawdź wynik linterem

Po konwersji uruchom linter, aby sprawdzić samą specyfikację, a nie tylko jej składnię. Tutaj każdy lokalny $ref jest sprawdzany podczas edycji.

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

JSON czy YAML dla specyfikacji API?

YAML do pisania

Długie opisy czyta się lepiej jako blokowy tekst YAML, a komentarze pozwalają opatrzyć specyfikację uwagami dla recenzentów.

JSON dla narzędzi

Generatory kodu, bramy API i SDK często najszybciej wczytują JSON, a wiele z nich udostępnia specyfikację pod /openapi.json.

Ten sam dokument

Oba formaty opisują to samo API. Konwertuj swobodnie w obu kierunkach; nic ze specyfikacji nie ginie.

Więcej narzędzi

Konwertery, walidatory i przewodniki krok po kroku dla każdego miejsca, w którym spotykają się JSON i YAML.

Najczęściej zadawane pytania

Jak przekonwertować plik OpenAPI JSON na YAML?

Wklej lub prześlij openapi.json i skopiuj YAML z prawego panelu albo pobierz go jako openapi.yaml. Struktura, wskaźniki $ref, przykłady i opisy pozostają dokładnie takie same.

Czy działa ze Swagger 2.0, a nie tylko z OpenAPI 3?

Tak. Konwerter działa na strukturze dokumentu, więc specyfikacje Swagger 2.0, OpenAPI 3.0 i OpenAPI 3.1 konwertują się tak samo, w obu kierunkach.

Dlaczego $ref: '#/components/...' jest w cudzysłowie?

W YAML znak # po spacji rozpoczyna komentarz. Bez cudzysłowów wszystko po $ref: zostałoby potraktowane jako komentarz, a odwołanie byłoby puste. Konwerter automatycznie ujmuje je w cudzysłowy.

Dlaczego kody odpowiedzi są zapisane jako '200'?

OpenAPI wymaga, aby kody odpowiedzi były kluczami typu string. 200 bez cudzysłowu jest w YAML liczbą całkowitą; większość narzędzi to akceptuje, ale ścisłe walidatory nie. Cudzysłowy sprawiają, że specyfikacja jest poprawna wszędzie.

Jak przekonwertować YAML OpenAPI z powrotem na JSON?

Zmień kierunek na YAML → JSON przełącznikiem nad edytorem albo użyj konwertera YAML na JSON. Kotwice w YAML są rozwijane, ponieważ JSON nie ma tego rodzaju odwołań.