Jak szybko pokazać innym jak działa API, które stworzyłeś.
Na co pozwala OpenAPI
Dzięki OpenAPI (openapis.org) możesz udostępnić specyfikację techniczną swojego interfejsu API w formacie deklaratywnym, opartym na JSON lub YAML. Tak utworzona dokumentacja będzie zawierać wszystkie dane niezbędne do interakcji z interfejsem API, w tym punkty końcowe (endpoints), parametry żądań (parametry zapytań lub treść) oraz odpowiedzi (kod stanu, dane). Ponadto możesz dodać dodatkowe teksty opisowe i grafiki, aby lepiej wytłumaczyć działanie poszczególnych opcji.
Pamiętaj – niestaranna dokumentacja to jeden z grzechów głównych dewelopera.
Podstawowym narzędziem do szybkiego utworzenia dokumentacji jest generator dokumentacji. Generatory dokumentacji przyjmują specyfikację OpenAPI i przekształcają ją w czytelną dla człowieka formę, głównie strony HTML. Układ wyników dokumentacji jest bardzo zróżnicowany, podobnie jak funkcje: wyszukiwanie pełnotekstowe, składanie i rozwijanie przykładów kodu, klikalne linki a nawet wykonywanie wywołań API.
W openapi.tools można znaleźć sporo służących temu narzędzi – przyjrzyjmy się paru z nim.
RapiDoc
RapiDoc to konfigurowalna przeglądarka dokumentacji. To narzędzie umożliwia załadowanie dowolnej specyfikacji OpenAPI, do której można uzyskać dostęp za pośrednictwem adresu URL. Po prostu wklej link w małym pasku wyszukiwania, a zaraz potem możesz przejrzeć dokumentację.
Sprawdź oferty pracy na TeamQuest
RapiDoc tworzy strukturę API zgodnie z kolejnością leksykalną wszystkich punktów końcowych zawartych w specyfikacji. Poszczególne metody HTTP są reprezentowane różnymi kolorami, co sprawia, że reprezentacja jest raczej pstrokata. Po kliknięciu punktu końcowego otwiera się nowy widok: żądanie po lewej stronie, odpowiedź po prawej stronie. Strona zapytania zawiera już wszystkie informacje jakich można potrzebować: każde pole zawiera pełną dokumentację, w tym typ i opis. Żądanie można wyświetlić jako „wartość”, pokazując dane w formacie danych preferowanym dla tego konkretnego punktu końcowego i jego modelu, a także pełny opis modelu. Strona odpowiedzi pokazuje również przykład odpowiedzi i pełny model danych.
Wada? Brak opcji wyszukiwania (a przeglądarkowy skrót CTRL + F to nie to samo).
ReDoc
ReDoc jest podobny do RapiDoc: samodzielnie hostowana przeglądarka dokumentacji, za pomocą której można ładować i przeglądać dowolną specyfikację OpenAPI opartą na JSON. Uważaj, jeśli załadujesz obszerną specyfikację: na przykład specyfikacja Kubernetes o rozmiarze 4 MB ładuje się przez około 1 minutę…
Układ dokumentacji to trzy osobne jakby pasy z informacjami. Po lewej stronie znajduje się lista wszystkich punktów końcowych, pogrupowanych według wartości tagu w specyfikacji OpenAPI. W centrum znajduje się dokumentacja aktualnie wybranego punktu końcowego: opis, parametry i odpowiedzi. Wreszcie po prawej stronie widać zwijalny model żądań. Nie ma opcji kopiowania treści żądania, ale można skopiować model odpowiedzi.
Pozostałe
Slant to generator dokumentów, który musisz samodzielnie zainstalować i hostować. Jest nadal w fazie rozwoju i nie można go skonfigurować do pracy ze specyfikacją OpenAPI.
Są też płatne rozwiązania: ReadMe jest oparte o specyfikację OpenAPI, ale dokumentację można wzbogacić dodatkowymi przykładami, wskazówkami technicznymi, a nawet sekcją pomocy. Z kolei API Matic to narzędzie do tworzenia kompletnego portalu dla programistów w oparciu o specyfikację OpenAPI. Po zarejestrowaniu się, główna strona administratora pokazuje wszystkie „projekty API” i stamtąd możesz uzyskać dostęp do każdego projektu w celu edycji i konfiguracji.
