Walidator OpenAPI 3.1

Co narzędzie robi z plikami 3.1

Wersja 3.1 dostosowuje schematy do JSON Schema 2020-12. Ten walidator w ogóle nie zagląda do wnętrza schematów. Sprawdza tylko najwyższy poziom i wpisy ścieżek, dlatego funkcje schematów 3.1, takie jak tablice typów czy const, tutaj ani nie przechodzą, ani nie zawodzą. Sama wartość wersji również nie jest sprawdzana: każde pole openapi uznawane jest za obecne.

Dwa wzorce 3.1, na które warto uważać

OpenAPI 3.1 pozwala opisać dokument wyłącznie przez webhooks i pominąć paths. To narzędzie wymaga paths, więc taki plik zostaje zgłoszony błędem, mimo że specyfikacja na to pozwala. Dodanie pustego obiektu paths: {} spełnia kontrolę.

Lista metod używana tutaj to get, post, put, patch, delete, head, options, a także parameters, summary, description i servers. Metoda trace istnieje w specyfikacji, ale nie znajduje się na tej liście, więc wywołuje ostrzeżenie, które możesz zignorować, jeśli jest zamierzone. Ostrzeżenia nie czynią dokumentu nieprawidłowym.

Przykład krok po kroku

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Wynik: jeden błąd, “Missing ‘paths’ object.” Dodaj paths: {}, a struktura przejdzie kontrolę.

Kiedy stosować to narzędzie, a kiedy iść dalej

Tej strony użyj, aby potwierdzić, że plik 3.1 ma poprawny kształt, zanim otworzysz pull request lub udostępnisz go partnerowi. Kontrole są szybkie, a komunikaty proste. Gdy struktura jest w porządku, reguły schematów 3.1 nadal wymagają pełnego lintera, bo tam ukrywa się większość realnych błędów: niepoprawne deklaracje typów, zepsute referencje i brakujące definicje odpowiedzi. Traktuj oba kroki jako uzupełniające się, a nie jako alternatywę.

Jeśli oflagowane ostrzeżenie jest zamierzone, na przykład trace, opisz to w pull requeście, aby recenzenci nie zastanawiali się, o co chodzi. Ostrzeżenia nigdy nie zmieniają wyniku poprawności, więc można je zostawić. Błędy trzeba usunąć przed udostępnieniem pliku.