API – dokumentacja

Nieodzowną częścią budowanej aplikacji powinna być jej dokumentacja. Problem z dokumentami tworzonymi obok kodu jest to, że nie zawsze są one na bieżąco aktualizowane. Co zrobić by nasza dokumentacja była ciągle aktualna i była zmieniania w trakcie rozbudowy kodu ?

W moim przypadku dobrym podejściem okazało się, by dokumentację powiązać z testami. W przypadku aplikacji, którą rozwijałem w oparciu o framework Spring istnieje znakomite narzędzie jakim jest Spring REST Docs, które dla budowanych przez nas testów pozwala automatycznie w trakcie ich wykonywania generować żądania i odpowiedzi np. w postaci curl’a, które z kolei można w łatwy sposób agregować do 1 dokumentu za pomocą AsciiDoc. Dzięki temu gdy zmienimy nasze API, to zmienimy testy i automatycznie zmieni się nasza dokumentacja 🙂

Troszkę inne podejście jest w przypadku Swagger, który dostarcza wielu narzędzi nie tylko do tworzenia dokumentacji, ale również do generowania kodu. Zaletą tego podejścia jest niezależność od języka (Spring używany jest dla Javy) oraz jego popularność.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *

Time limit is exhausted. Please reload CAPTCHA.