Napíšu jasnou dokumentaci API, kterou vaši vývojáři mohou sledovat od prvního dne

Proč většina dokumentace API selhává

Popisují koncové body a vynechávají části, které skutečně lidi zastavují: jak se autentizovat, jak vypadá realistický požadavek, co znamená chyba a co s ní dělat. Čtenář pak otevře tiket podpory, což je náklad, který má dokumentace odstranit.

Jak to píšu

Ze zdroje, ne z paměti. Přečtu si trasy, validační vrstvu a obsluhu chyb, pak sám zavolám API se skutečnými přihlašovacími údaji. Každý příklad v dokumentaci je požadavek, který jsem provedl, a odpověď, kterou jsem obdržel – žádné vymyšlené datové části, žádné stavové kódy, které koncový bod nikdy nevrací.

Co dokumentace obsahuje

• Autentizace: získání tokenu, jeho obnovení a co se stane, když vyprší uprostřed relace.
• Každý koncový bod s parametry, kompletní příklad požadavku a skutečný tvar odpovědi.
• Odkaz na chyby, který mapuje každý chybový kód na příčinu a opravu, namísto pouhého opakování zprávy.
• Cesta pro začátečníky, která nového vývojáře provede od nuly k úspěšnému volání za méně než deset minut.
• Vysvětlení omezení rychlosti, stránkování, webhooků a idempotence tam, kde se skutečně uplatňují.

Formát

Markdown ve vašem repozitáři, strukturovaný pro OpenAPI nebo dokumentační web – cokoli, co budete skutečně udržovat. Ukázky kódu v jazycích, na které se vaši uživatelé ptají, ověřené jejich spuštěním. Kolekce Postman nebo podobná kolekce je zahrnuta, pokud ji chcete.

Co potřebuji

Přístup k repozitáři nebo soubor OpenAPI, jeden funkční přihlašovací údaj pro testovací prostředí a jakékoli otázky, na které je váš tým podpory unavený odpovídat. Tyto otázky tvoří osnovu.

Není zahrnuto

Marketingový text. Toto dokumentuje, co software přesně dělá; vstupní stránka je jiné řemeslo.

Doba realizace a komunikace

První kompletní návrh obvykle dorazí do týdne a vy jej zkontrolujete proti otázkám, na které váš vlastní tým podpory neustále odpovídá. Raději budu opraven brzy inženýrem, který zná okrajové případy, než abych dodal něco vyleštěného a špatného. Každý příklad v konečném dokumentu byl proveden proti vašemu API, takže nic v něm není aspirativní.