Magidoc: szybkie i proste generowanie dokumentacji dla Twojego API GraphQL

Jedną z rzeczy, których większość programistów nie lubi robić, jest pisanie dokumentacji. Jest to na ogół postrzegane jako monotonne zadanie, do którego jesteśmy zmuszani, taki rodzaj obowiązku w procesie tworzenia oprogramowania. Często wydaje się to stratą czasu, który mógłby zostać przeznaczony na kodowanie czegoś nowego dla Twojej aplikacji webowej lub innego projektu. Zamiast tego trzeba wykorzystać ten czas, żeby wyjaśnić kod innym. Jednak mimo wszystko wszyscy to robią, bo to w zasadzie brama do Twojego projektu dla innych osób. Zazwyczaj warto więc poświęcić trochę czasu na stworzenie dokumentacji, aby ułatwić pracę tym, którzy mogą być zainteresowani tym, nad czym pracujesz.

To nie strata czasu

Dobrze napisana i szczegółowa dokumentacja może być naprawdę dużym atutem, dlatego technologiczni giganci tacy jak Google czy Facebook dbają o nią w projektach, którymi się opiekują. Jeśli szukasz inspiracji, możesz sprawdzić dokumentację Django jako przykład szczególnie dobrze zrobionej dokumentacji. Nawet jeśli teraz nie przepadasz za pisaniem dokumentacji, może ona oszczędzić Ci wielu problemów w przyszłości, gdy będziesz chciał zainteresować innych swoją aplikacją webową, biblioteką, frameworkiem czy czymkolwiek, nad czym aktualnie pracujesz. Choć niektórzy uważają dokumentację za nieistotną, w rzeczywistości odgrywa ona dużą rolę, zwłaszcza w przypadku rzeczy o wysokim progu wejścia albo dużej złożoności. W przypadku różnych narzędzi dokumentacja może decydować o ich sukcesie lub porażce, bo w rozwoju aplikacji większość devów woli zaczynać z jasnym obrazem sytuacji, zamiast wszystko rozpracowywać na własną rękę. Najlepiej też zacząć pisać dokumentację stopniowo, tak aby rosła wraz z Twoim projektem. W przeciwnym razie możesz skończyć z ogromem pracy do zrobienia w przyszłości, dokumentując wszystko od zera dla projektu, który już znacząco się rozrósł.

Magidoc

Na szczęście są narzędzia, które mogą pomóc w tworzeniu dokumentacji. Oczywiście nie zrobią za Ciebie dosłownie wszystkiego (przynajmniej jeszcze nie), ale jeśli priorytetem jest wykonanie pracy jak najszybciej, każde narzędzie przyspieszające ten proces to ogromne ułatwienie. Jednym z takich narzędzi jest Magidoc — statyczny generator dokumentacji stworzony do GraphQL API, napisany w Svelte. Jako że zależy nam na jak najszybszym uporaniu się z dokumentacją, przejdźmy po prostu do funkcji:

• szybko i prosto: Magidoc działa od razu po instalacji i potrafi wygenerować dokumentację dla każdego zapytania, typu, subskrypcji i mutacji w Twoim GraphQL API, wykorzystując Twój schemat lub żywy endpoint przez zapytanie introspekcyjne.
• łatwo konfigurowalny: Magidoc korzysta z prostego pliku konfiguracyjnego w JavaScript, dzięki czemu możesz dostosowywać go wedle uznania.
• wsparcie dla markdown: Magidoc obsługuje markdown, więc formatowanie dokumentacji jest tak łatwe, jak pisanie posta na forum. Obsługuje też zaawansowane funkcje markdown — jeśli potrzebujesz tabel czy osadzonego HTML, również dasz radę.
• przydatne wtyczki: Magidoc oferuje wrapper Svelte dla PrismJS oraz parser markdown, który renderuje komponenty Svelte i wspiera GitHub Flavored Markdown dla osób chcących nieco urozmaicić swoją dokumentację.

Doceniaj pomoc

Jak widać, podejście jest szybkie i konkretne — używasz domyślnych ustawień i otrzymujesz podstawową dokumentację, która przedstawia, czym jest Twoje API, a następnie możesz pracować nad konfiguracją i markdownem, by dodać więcej szczegółów i poprawić wygląd całości. Ile czasu na to poświęcisz — to już zależy od Ciebie. Jedni będą w zupełności zadowoleni z podstawowej dokumentacji i cieszyć się, że już mają to z głowy; inni będą chcieli jeszcze trochę podłubać. Kluczowa sprawa to sprawić, by pisanie dokumentacji było mniej uciążliwym zadaniem — co Magidoc zdecydowanie ułatwia. To zresztą narzędzie mające zaledwie kilka miesięcy i ciągle się rozwija, więc można spodziewać się nowych funkcji w przyszłości. Jeśli jednak nie interesują Cię rozbudowane opcje, już teraz Magidoc zapewnia sporo rzeczy od razu po instalacji, więc jeśli po prostu chcesz szybko zakończyć temat dokumentacji, to narzędzie pomoże Ci wystartować ekspresowo.