Walidator OpenAPI JSON

Typowe błędy JSON, które powodują niepowodzenie

JSON jest bardziej rygorystyczny niż YAML, więc większość niepowodzeń ręcznie edytowanego pliku wynika ze składni, a nie z projektu API. Najczęstsze przyczyny to przecinek po ostatniej właściwości, pojedyncze cudzysłowy zamiast podwójnych, komentarz (JSON ich nie dopuszcza) albo brakujący zamykający nawias klamrowy po długim obiekcie paths. Uszkodzony plik zwykle kończy się komunikatem “Could not parse as JSON or YAML” albo brakującymi polami, bo nie udało się odczytać niczego użytecznego.

Jeśli widzisz tylko błąd parsowania, najpierw znajdź błąd składni. Kontrole strukturalne uruchamiają się dopiero wtedy, gdy dokument da się odczytać jako obiekt.

Przykład krok po kroku

Weź ten niewielki dokument:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Da się go sparsować, a pole openapi i obiekt paths są obecne. Raport i tak pokaże:

Jeden błąd oznacza, że dokument nie jest uznany za poprawny. Dodaj "version": "1.0.0" do info i zmień nazwę klucza na /orders. Kolejne uruchomienie usunie oba wyniki.

Co oznacza zaliczenie, a czego nie oznacza

Czysty raport oznacza, że szkielet jest poprawny. Nie podąża za linkami $ref, nie sprawdza schematów i nie potwierdza, że każda operacja ma odpowiedzi. Traktuj go jako szybką bramkę przed zatwierdzeniem pliku, a następnie uruchom pełny linter, aby sprawdzić głębsze reguły.

Praktyczny przepływ pracy dla specyfikacji JSON

Trzymaj specyfikację w systemie kontroli wersji i wklejaj ją tutaj przed każdym commitem, który dotyczy paths. Ponieważ kontrola jest szybka, działa jak krok zdroworozsądkowy po scaleniu zmian kilku osób, kiedy powtórzone klucze lub źle umieszczony nawias są najbardziej prawdopodobne. Jeśli Twój JSON generuje skrypt budujący, wklejaj wygenerowany wynik, a nie szablon, aby sprawdzić to, co naprawdę dostaną czytelnicy. Gdy raport jest czysty, możesz udostępnić plik lub przekazać go generatorowi dokumentacji z większą pewnością, że struktura najwyższego poziomu jest poprawna.