YAML do pisania
Długie opisy czyta się lepiej jako blokowy tekst YAML, a komentarze pozwalają opatrzyć specyfikację uwagami dla recenzentów.
Konwertuj specyfikacje API między JSON a YAML bez psucia ścieżek $ref i kodów odpowiedzi.
Każdy wiersz wyniku w domyślnym formatowaniu obok ścieżki wartości, którą zawiera. Kliknij wiersz, aby skopiować ścieżkę.
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.
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.
{
"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 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.
Po konwersji uruchom linter, aby sprawdzić samą specyfikację, a nie tylko jej składnię. Tutaj każdy lokalny $ref jest sprawdzany podczas edycji.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Długie opisy czyta się lepiej jako blokowy tekst YAML, a komentarze pozwalają opatrzyć specyfikację uwagami dla recenzentów.
Generatory kodu, bramy API i SDK często najszybciej wczytują JSON, a wiele z nich udostępnia specyfikację pod /openapi.json.
Oba formaty opisują to samo API. Konwertuj swobodnie w obu kierunkach; nic ze specyfikacji nie ginie.
Konwertery, walidatory i przewodniki krok po kroku dla każdego miejsca, w którym spotykają się JSON i 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.
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.
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.
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.
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ń.