Softonic

Walidator OpenAPI YAML

Krok 1 / 2
Dalej

Wklej swój openapi.yaml, a walidator sprawdzi elementy, których potrzebuje każda specyfikacja: pole wersji, obiekt info z title i version oraz obiekt paths. Ostrzega też o kluczach ścieżek bez wiodącego ukośnika i o kluczach operacji, których nie rozpoznaje.

Jak sprawdzić plik OpenAPI YAML

  1. 1

    Skopiuj YAML

    Skopiuj pełną zawartość `openapi.yaml` lub `swagger.yaml`, zachowując wcięcia dokładnie tak, jak są.

  2. 2

    Wklej do pola

    Wklej go w pole dokumentu OpenAPI / Swagger. W YAML wcięcia są strukturą, więc nie przepisuj ich ani nie zmieniaj układu.

  3. 3

    Uruchom walidację

    Przejdź do kroku wyników i przeczytaj błędy oraz ostrzeżenia.

  4. 4

    Popraw i sprawdź ponownie

    Napraw każdy wskazany element w swoim pliku, wklej nową wersję i uruchom kontrolę ponownie.

Dlaczego wcięcia wpływają na wynik

W YAML zagnieżdżenie kluczy decyduje o tym, do którego obiektu należy pole. Jeśli version ma to samo wcięcie co info, zamiast poziom niżej, dokument nadal jest czytelnym YAML, ale info.version nie istnieje i kontrola to zgłasza. Tak samo jest z paths: klucz ścieżki wcięty przez pomyłkę pod info oznacza, że obiekt paths na najwyższym poziomie zniknął.

Używaj spacji, a nie tabulatorów, i zachowuj stały krok, na przykład dwie spacje na poziom.

Przykład krok po kroku

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

Pole wersji, info.title i paths są obecne, a /pets zaczyna się od ukośnika, z get jako znaną metodą. Brakuje jednej rzeczy: info.version. Raport wymienia:

Wynik Typ
info.version is required. Błąd

Dodaj version: 1.0.0 pod info, wcięte o dwie spacje, a dokument zostanie uznany za poprawny strukturalnie.

Trzymaj dokumenty proste, aby odczyt był niezawodny

Kontrola najlepiej czyta zwykłe mapowania YAML: proste linie klucz: wartość zagnieżdżone z konsekwentnymi wcięciami. Jeśli dokument z zaawansowanymi funkcjami YAML, takimi jak kotwice czy bloki wieloliniowe, zostaje uznany za nieczytelny albo pokazuje brakujące pola, spróbuj kopii tej specyfikacji w JSON, aby sprawdzić, czy problem leży w treści, czy w składni YAML.

Czysty wynik potwierdza tylko szkielet. Nie rozwiązuje odnośników $ref i nie sprawdza schematów.

Praktyczny przepływ pracy dla specyfikacji YAML

Edytuj małymi krokami i sprawdzaj na bieżąco. Po dodaniu nowej ścieżki albo przeniesieniu bloku wklej plik ponownie, aby źle ustawione wcięcie zostało wychwycone, gdy zmiana jest świeża. Gdy dzielisz dużą specyfikację na kilka plików, wklej połączoną wersję, bo ta kontrola odczytuje tylko tekst, który jej podasz, i nie wczytuje innych plików. Kopiuj z edytora, a nie ze strony wyświetlonej w przeglądarce, bo strony mogą zamieniać spacje i cudzysłowy na podobnie wyglądające znaki, które zmieniają sposób odczytu YAML.

Pamiętaj też, że raport zawiera tylko to, co kontrola jest w stanie zobaczyć. Czysty wynik dla pliku YAML oznacza, że szkielet najwyższego poziomu jest poprawny, a nie że każda operacja, schemat lub referencja wewnątrz niego jest poprawna.

Najczęściej zadawane pytania

Spacji. YAML nie przyjmuje tabulatorów jako wcięć, a tabulator może sprawić, że dokument stanie się nieczytelny albo że pola trafią na zły poziom.

Zwykle pole ma złe wcięcie i należy do innego obiektu, niż zamierzałeś. Porównaj jego wcięcie z kluczem nadrzędnym.

Ta kontrola sprawdza tylko obecność pola openapi lub swagger, a nie jego wartość, więc wersje w cudzysłowach i bez nich przechodzą. Stosowanie cudzysłowu dla "2.0" w Swagger to mimo to dobry nawyk.

Tak. Dokument jest najpierw odczytywany jako JSON, a jeśli to się nie uda, jako YAML, więc oba formaty działają w tym samym polu.

Powiązane narzędzia

Generator konfiguracji webpack

Utwórz plik webpack.config.js dla webpacka 5 do czystego JavaScriptu, Reacta lub Vue: TypeScript, Babel, CSS lub Sass, obrazy, HtmlWebpackPlugin, serwer deweloperski i polecenie npm install.

Generator kolorów analogicznych

Twórz pięciokolorowe palety analogiczne z dowolnego koloru bazowego: klasyczną trójkę, dwie zewnętrzne barwy oraz wartości hex, RGB i HSL.

Walidator XSD

Waliduj dokument XML wobec schematu XSD i zgłaszaj niezgodności elementów i typów z dokładnymi numerami wierszy.

Generator fikcyjnych numerów telefonu

Generuj do 50 fikcyjnych numerów z oficjalnie zastrzeżonych zakresów w pięciu krajach.

Kod na obraz

Wklej kod, ustaw motyw, kolory, rozmiar czcionki, odstępy, nagłówek i numery wierszy, sprawdź podgląd canvas i pobierz PNG. Renderowanie zwykłego tekstu, bez podświetlania składni.

Dekoder Protocol Buffers

Dekoduj lokalnie bajty Protobuf z zapisu hex, Base64, Base64URL, tekstu lub pliku, analizuj pola i eksportuj prywatny raport.

Narzędzie jest dostępne w innych językach

Poradniki i zastosowania