Softonic

Walidator specyfikacji OpenAPI online

Krok 1 / 2
Dalej

Wklej powyżej swoją specyfikację OpenAPI lub Swagger, aby otrzymać listę błędów i ostrzeżeń. Ta strona wyjaśnia, co oznacza każdy komunikat i jak go naprawić, dzięki czemu szybko przejdziesz od czerwonego raportu do czystego. Błędy czynią dokument niepoprawnym, ostrzeżenia nie.

Jak sprawdzić specyfikację i zareagować na raport

  1. 1

    Wklej specyfikację

    Wklej dokument w formacie JSON lub YAML do pola.

  2. 2

    Otwórz wyniki

    Przejdź do kroku wyników, aby zobaczyć komunikat o poprawności albo listę błędów.

  3. 3

    Dopasuj każdy komunikat

    Znajdź komunikat w tabeli poniżej i zastosuj poprawkę w pliku źródłowym.

  4. 4

    Wklej ponownie

    Powtarzaj, aż nie zostaną żadne błędy, a potem zdecyduj, które ostrzeżenia warto poprawić.

Jak czytać komunikaty o błędach

Komunikat Znaczenie Naprawa
Could not parse as JSON or YAML. Tekstu nie da się odczytać w żadnym z formatów Popraw składnię: zbędne przecinki, złe wcięcia, niedomknięte nawiasy
Missing ‘openapi’ or ‘swagger’ version field. Brak klucza wersji na najwyższym poziomie Dodaj openapi: 3.0.3 lub swagger: "2.0"
Missing ‘info’ object. Brak sekcji info Dodaj info z title i version
info.title is required. info nie ma title Dodaj title w info
info.version is required. info nie ma version Dodaj version w info (wersję Twojego API)
Missing ‘paths’ object. Brak sekcji paths Dodaj paths, nawet pustą na początku

Błędy decydują o tym, czy dokument zostanie uznany za poprawny. Usuń je wszystkie w pierwszej kolejności.

Jak czytać ostrzeżenia

Komunikat Znaczenie Naprawa
Path ‘x’ should start with ‘/’. Klucz w paths nie zaczyna się od ukośnika Zmień nazwę na /x
Unknown method ‘x’ on /path. Klucz pod ścieżką nie znajduje się na liście znanych metod Sprawdź literówkę albo zignoruj, jeśli to celowe rozszerzenie lub trace

Lista znanych kluczy to get, post, put, patch, delete, head, options, parameters, summary, description i servers. Rozszerzenia dostawców zaczynające się od x- nie znajdują się na tej liście, więc również pojawiają się jako ostrzeżenia.

Czego kontrola online nie jest w stanie ocenić

Raport obejmuje wyłącznie strukturę. Nie podąża za odnośnikami $ref, nie sprawdza definicji schematów ani nie oznacza brakujących wartości operationId. Traktuj zaliczenie jako potwierdzenie, że plik ma kształt dokumentu OpenAPI, a przed publikacją dokumentacji lub generowaniem kodu klienta użyj pełnego lintera.

Wskazówki przy długim raporcie

Zacznij od góry: błąd parsowania sprawia, że nic innego nie jest wiarygodne, więc napraw go najpierw. Następnie zajmij się brakującymi polami najwyższego poziomu, bo szybko je dodać. Dopiero potem spójrz na ostrzeżenia dotyczące ścieżek. Po każdej rundzie zmian wklejaj cały plik, a nie fragment, bo kontrole potrzebują pełnego dokumentu, aby znaleźć info i paths. Raport bez błędów z kilkoma celowymi ostrzeżeniami to normalny i akceptowalny końcowy stan.

Najczęściej zadawane pytania

Błędy oznaczają, że dokument zostaje uznany za niepoprawny. Ostrzeżenia wskazują elementy warte uwagi, na przykład ścieżkę bez ukośnika na początku, ale nie zmieniają wyniku poprawności.

Niekoniecznie. Oznacza to, że struktura najwyższego poziomu jest na miejscu. Schematy, referencje i odpowiedzi nie są badane.

Klucze pod ścieżką są porównywane z ustaloną listą metod HTTP i kilkoma polami elementu ścieżki. Klucz x- nie znajduje się na tej liście, więc zostaje oflagowany jako ostrzeżenie. Możesz go zostawić.

Nie. Idą w kolejności kontroli: najpierw pole wersji, potem info, a na końcu paths. Nie ma numerów wierszy.

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