Sprawdzanie kontraktu API

Wklejasz (lub przesyłasz) specyfikację bazową (starą) i rewizyjną (nową) OpenAPI 3.x, a narzędzie przechodzi przez każdą ścieżkę, parametr, request body, response, wymóg security oraz schemat w obu wersjach, po czym raportuje zmiany: dodane lub usunięte endpointy, zmiany wymagalności parametrów i pól requestu, zawężone typy lub enumy, zniknięte pola response lub kody statusu, zmiany wymogów security oraz zmiany kompozycji allOf/oneOf/anyOf.

Wszystko, co mogłoby przestać działać u istniejącego klienta: usunięty endpoint, parametr lub pole requestu, które stało się wymagane, usunięte pole response lub kod statusu, pole, które nie jest już gwarantowane w response, albo zawężony typ/enum (w tym tablice typów nullable z OpenAPI 3.1, np. usunięcie "null" z `["string", "null"]`). Nowe endpointy, nowe pola opcjonalne i nowe pola response są addytywne i pokazywane osobno jako bezpieczne.

Tak. Dodane/usunięte wymogi security (globalne i per operacja), zmiany definicji schematu security (np. przeniesienie API key z nagłówka do parametru zapytania), nowo oznaczone jako przestarzałe operacje oraz zmiany adresu URL serwera - wszystko to jest raportowane jako ustalenia informacyjne, a nie łamiące lub bezpieczne, ponieważ (zgodnie z domyślnym poziomem istotności, jaki nadaje tym kontrolom samo oasdiff) żaden kierunek nie jest zawsze poprawny lub błędny; to Ty decydujesz, czy ma to znaczenie dla Twojego API.

Tak. Elementy `allOf` są rozwiązywane i scalane przed porównaniem, więc pole wymagane dodane głęboko wewnątrz złożonego schematu wciąż zostanie wykryte. Zestawy wariantów `oneOf`/`anyOf` są porównywane i oznaczane jako informacyjne, gdy wariant zostanie dodany lub usunięty, ponieważ to, czy dana zmiana jest łamiąca, zależy od sposobu, w jaki Twoi klienci rozróżniają warianty.

Nie - to narzędzie porównuje wyłącznie specyfikacje OpenAPI 3.x. Swagger 2.0 (starszy format) strukturyzuje parametry i body inaczej, więc zastosowanie tych samych reguł dałoby błędne wyniki. Wklejenie dokumentu Swagger 2.0 zwraca czytelny błąd zamiast cichego, błędnego diffa.

Nie. Parsowanie i porównanie odbywają się w całości w Twojej przeglądarce - specyfikacja nigdy nie opuszcza Twojego urządzenia, w przeciwieństwie do większości innych narzędzi do porównywania OpenAPI, które przetwarzają przesłany plik na własnym serwerze, nawet gdy twierdzą, że go nie przechowują. Dotyczy to również opcji przesyłania pliku metodą przeciągnij i upuść: plik jest odczytywany lokalnie i nigdy nie jest transmitowany.

Porównuje treści request i response typu `application/json`, co obejmuje zdecydowaną większość API REST, ale nie ocenia innych typów treści, nagłówków response, opisów ani przykładów. `$ref` wskazujący poza dokument (osobny plik lub URL) jest raportowany jako nierozwiązywalny, a nie po cichu pomijany.

Tak, jedno i drugie. Każde pole przyjmuje niezależnie JSON lub YAML i wykrywa, którego formatu użyto, więc możesz porównać bazową specyfikację JSON z rewizją w YAML lub odwrotnie. Możesz też przeciągnąć plik .json/.yaml/.yml na dowolne z pól albo użyć przycisku Upload file - plik jest odczytywany w przeglądarce i nigdy nigdzie nie jest przesyłany.

Działa z każdym dokumentem zawierającym pole "openapi": "3.x" oraz obiekt "paths", co obejmuje zarówno wersję 3.0, jak i 3.1 - łącznie z tablicową formą `type` z 3.1 (np. `["string", "null"]`) - i odrzuca wyłącznie dokumenty, które wyglądają jak Swagger 2.0.

Obsługiwane są Text (.txt), Markdown (.md) i JSON (.json) - wybierz jeden z rozwijanej listy formatów obok Download report przed pobraniem. Eksport JSON zawiera pełną listę ustaleń wraz z liczbą wystąpień dla każdego poziomu istotności, więc można go przekazać do innego skryptu (np. kontroli CI), jeśli tego potrzebujesz.

Działa oba sposoby: naciśnij Compare, aby uruchomić porównanie natychmiast, albo po prostu kontynuuj pisanie - po krótkiej przerwie porównanie uruchomi się automatycznie. Możesz też nacisnąć Ctrl+Enter (Cmd+Enter na Macu) w dowolnym z pól, aby porównać od razu, bez oczekiwania.