Világos API dokumentációt írok, amelyet a fejlesztői az első naptól kezdve követhetnek

Miért hibás a legtöbb API-dokumentáció

Leírják a végpontokat, és kihagyják azokat a részeket, amelyek valójában megállítják az embereket: hogyan kell hitelesíteni, hogyan néz ki egy valósághű kérés, mit jelent a hiba, és mit kell tenni vele. Az olvasó ezután támogatási jegyet nyit, ami az a költség, amelyet a dokumentáció hivatott megszüntetni.

Hogyan írom

A forrásból, nem emlékezetből. Elolvasom az útvonalakat, az érvényesítési réteget és a hibakezelőket, majd magam hívom meg az API-t valós hitelesítő adatokkal. A dokumentációban szereplő minden példa egy általam végrehajtott kérés és egy általam kapott válasz – nincsenek kitalált adatok, nincsenek olyan állapotkódok, amelyeket a végpont soha nem ad vissza.

Mit tartalmaz a dokumentáció

• Hitelesítés: token beszerzése, frissítése, és mi történik, ha a munkamenet közben lejár.
• Minden végpont paraméterekkel, egy teljes példakérés és a valós válaszforma.
• Egy hibareferencia, amely minden hibakódot egy okhoz és egy javításhoz rendel, ahelyett, hogy csak megismételné az üzenetet.
• Egy kezdő útmutató, amely egy új fejlesztőt nulláról egy sikeres hívásig vezet kevesebb mint tíz perc alatt.
• A sebességkorlátok, lapozás, webhookok és idempotencia magyarázata ott, ahol ténylegesen alkalmazandók.

Formátum

Markdown a tárolóban, strukturálva OpenAPI vagy dokumentációs oldal számára – bármelyiket is fogja ténylegesen karbantartani. Kódminták az Ön felhasználói által kért nyelveken, futtatással ellenőrizve. Postman vagy hasonló gyűjtemény mellékelve, ha szeretne.

Amire szükségem van

Tároló hozzáférés vagy az OpenAPI fájl, egy működő hitelesítő adat egy tesztkörnyezethez, és bármilyen kérdés, amire a támogatási csapata már belefáradt a válaszadásba. Ezek a kérdések alkotják a vázlatot.

Nem tartalmazza

Marketing szöveg. Ez pontosan azt dokumentálja, amit a szoftver csinál; a nyitóoldal egy másik szakma.

Átfutási idő és kommunikáció

Az első teljes tervezet általában egy héten belül elkészül, és Ön áttekinti azt a kérdések alapján, amelyekre a saját támogatási csapata folyamatosan válaszol. Inkább korán kijavítana az a mérnök, aki ismeri a szélsőséges eseteket, mintsem valami csiszolt, de hibás dolgot szállítana. A végső dokumentumban szereplő minden példa az Ön API-ja ellen lett végrehajtva, így semmi sem aspirációs benne.