Napiszę przejrzystą dokumentację API, którą Twoi programiści będą mogli śledzić od pierwszego dnia

Dlaczego większość dokumentacji API zawodzi

Opisują punkty końcowe i pomijają części, które faktycznie powstrzymują ludzi: jak się uwierzytelnić, jak wygląda realistyczne żądanie, co oznacza błąd i co z nim zrobić. Czytelnik otwiera wtedy zgłoszenie do pomocy technicznej, co jest kosztem, który dokumentacja ma na celu wyeliminować.

Jak to piszę

Ze źródła, nie z pamięci. Czytam trasy, warstwę walidacji i obsługę błędów, a następnie sam wywołuję API z prawdziwymi danymi uwierzytelniającymi. Każdy przykład w dokumentacji to żądanie, które wykonałem, i odpowiedź, którą otrzymałem — bez wymyślonych ładunków, bez kodów statusu, których punkt końcowy nigdy nie zwraca.

Co zawiera dokumentacja

• Uwierzytelnianie: uzyskiwanie tokena, jego odświeżanie i co się dzieje, gdy wygaśnie w trakcie sesji.
• Każdy punkt końcowy z parametrami, kompletny przykład żądania i rzeczywisty kształt odpowiedzi.
• Odwołanie do błędów, które mapuje każdy kod błędu do przyczyny i rozwiązania, zamiast tylko powtarzać komunikat.
• Ścieżka dla początkujących, która prowadzi nowego programistę od zera do udanego wywołania w mniej niż dziesięć minut.
• Limity szybkości, paginacja, webhooki i idempotencja wyjaśnione tam, gdzie faktycznie mają zastosowanie.

Format

Markdown w Twoim repozytorium, ustrukturyzowany dla OpenAPI lub witryny dokumentacji — cokolwiek faktycznie będziesz utrzymywać. Próbki kodu w językach, o które pytają Twoi użytkownicy, zweryfikowane przez ich uruchomienie. Kolekcja Postman lub podobna w zestawie, jeśli chcesz.

Czego potrzebuję

Dostęp do repozytorium lub plik OpenAPI, jedno działające poświadczenie dla środowiska testowego i wszelkie pytania, na które Twój zespół wsparcia jest zmęczony odpowiadaniem. Te pytania stanowią zarys.

Nie wliczone

Teksty marketingowe. To dokumentuje, co dokładnie robi oprogramowanie; strona docelowa to inna sztuka.

Czas realizacji i komunikacja

Pierwszy kompletny projekt zazwyczaj pojawia się w ciągu tygodnia, a Ty przeglądasz go pod kątem pytań, na które Twój własny zespół wsparcia ciągle odpowiada. Wolę być poprawiony wcześnie przez inżyniera, który zna przypadki brzegowe, niż dostarczyć coś dopracowanego i błędnego. Każdy przykład w ostatecznym dokumencie został wykonany na Twoim API, więc nic w nim nie jest aspiracyjne.