Útmutató csodálatos API-dokumentációk készítéséhez és automatizált teszteléshez

Üdvözöljük! Ha itt szeretné elindítani az API-dokumentációt és az automatizált tesztelést, akkor jó helyen jár. Lehet, hogy az az ötlete támad, hogy API-dokumentációs mérnökként kezdje el, de nem tudja, hol kezdje, ezért ne aggódjon tovább, mert leírom az API-dokumentáció megkezdéséhez szükséges lépéseket.

Először is kezdjük az API-dokumentáció jelentésével, és felosztjuk, hogy jobban megértsük, mi az API? Nos, ez az alkalmazásprogramozási felület rövidítése, és többféle típusa van, de a legújabb trend a REST API. Folytathatjuk a dokumentáció jelentésének megismerésével is; A dokumentáció olyan megjegyzésekként definiálható, amelyek elmagyarázzák az API függvényeinek, könyvtárainak és végpontjainak használatát.

Az API-dokumentáció oka

Miért dokumentáljuk az API-kat? Az API-k célja, hogy biztonságosak legyenek, és ez azt jelenti, hogy nem bárki megtekintheti a forrásprogramot, hanem az API-t más mérnökök is használni fogják, és a menedzsment számára megmutatható, hogy megértsék az API működését és legfőképpen szükség lesz harmadik feleknek, például partnereknek vagy ügyfeleknek, akik használni fogják az API-t. Az API-dokumentáció az API működésének közvetítésének módja, hogy más felek könnyebben tudják használni az API-kat.

Egy másik szempont, amit meg kell vizsgálni, hogy mivel van egy világos dokumentum, amely elmagyarázza az API használatát, ez azt jelenti, hogy kevesebb kérdés lesz az API integrálásával vagy egy adott végpont használatával kapcsolatban, ha új ügyfelek vannak, ami jelentős csökkenést eredményez. a támogató tevékenységek költségeiben.

Egy jó API-dokumentáció jellemzői

  • Egyszerűség
  • Pontosság
  • Relevancia
  • Teljesség
  • A mozaikszavak kifejtése
  • Tartalmazza a célt
  • Erőforrás leírása
  • Végpontok, URI-minták és HTTP-módszerek
  • Mintarészletek
  • Útmutatók
  • Hitelesítés és engedélyezés
  • Paraméterek és fejlécek
  • Hibakódok és hibakezelés
  • API verziószámítás és változásnapló
  • Támogatás elérhetőségei

Egyszerűség – a jó API-dokumentációnak a lehető legegyszerűbbnek kell lennie, olyan egyértelműnek kell lennie, hogy bárki, aki elolvassa, megértse. Ez azért van, mert nem mindenki, aki használni fogja a dokumentációt, mérnök, és nem akar olyan embereket, akik használd, hogy elveszj.

Pontosság – jó API-dokumentáció írásakor jó tudni, hogy a dokumentációban szereplő mindennek pontosnak kell lennie, hogy ne vezesse félre a dokumentációt használó feleket. Ne feledje, hogy az API-dokumentáció fő célja, hogy eligazítsa az embereket a API és nem fordítva.

Relevancia – egy jó API-dokumentációt nézve csak releváns információkat tartalmaz. Írás közben próbálja meg megosztani a releváns információkat, az ügyfeleknek nem igazán kell tudniuk, hogy hány ember dolgozott az API-n vagy valami hasonlón, ezért ne tegyen felesleges információkat a dokumentumokba.

Teljesség – amennyire azt szeretnénk, hogy az API dokumentáció a lehető legegyszerűbb legyen, és csak a releváns információkról írjunk, fontos, hogy az API dokumentáció nagyon teljes legyen, ne hagyjon ki egyetlen részletet sem az írás során, ügyeljen arra, hogy minden szempontot lefedjen. a színvonal fenntartása.

A mozaikszó kifejtése – az API-dokumentáció minden egyes rövidítését ki kell fejteni, hogy az ügyfelek megértsék, mit jelent, vegyük például az „MTA”-t, ami most egy mozaikszó, de csak sejtheti, mi az, és ettől lesz az API-dokumentáció. kevésbé pontos.

Tartalmazzon célt – API-dokumentáció írásakor fontos megjegyezni, hogy a dokumentumnak tartalmaznia kell az API-dokumentáció célmeghatározását, hogy aki kézhez kapja, az segítsen megtudni, hogy jogosult-e az API használatára.

Erőforrás leírása – az API dokumentációban minden végponthoz legyen egy rövid leírás, amely leírja, hogy mire való a végpont, és hogyan fogják használni, legyen rövid és tömör.

Végpontok, URI-minták és HTTP-metódusok – az API-dokumentációnak tartalmaznia kell az összes végpontot, és minden végponthoz egyértelmű dokumentációnak kell lennie az URI-mintákról, függetlenül attól, hogy van-e lekérdezési paramétere vagy sem, valamint a dokumentációnak meg kell mutatnia a kérési metódust, amely lehet GET , KÖZZÉTÉTEL, TÖRLÉS stb.

Mintarészletek – minden olyan szakaszban, ahol dokumentálják a végpontokat, rendelkeznie kell egy mintarészlettel is, amely legalább 3 mintakérelem-részletet mutat be a megfelelő mintaválaszokkal együtt. Tartalmaznia kell egy sikeres kérést, egy rossz kérést és egy szélső esetre vonatkozó kérést; a használati esettől függően több példa is lehet.

Útmutatók – az útmutatók különböző formájúak lehetnek attól függően, hogy Ön hol dolgozik, a szervezet útmutatóként videókat vagy írásos dokumentumokat használhat útmutatóként. Az útmutatók egyszerűbb áramlást biztosítanak, így irányítják a felhasználót, hogy melyik végponttal kezdje, és hol ér véget, megmondja a végpontok közötti kapcsolatot.

Hitelesítés és engedélyezés – az API-dokumentációnak mindig tájékoztatnia kell a felhasználót, hogy az egyes végpontokon milyen hitelesítési és engedélyezési módszert alkalmaznak, egyesek cookie-kat használnak, vannak, akik munkameneteket használnak, és vannak más módszerek is, ezért célszerű megadni, hogy melyik módszert használják a különböző végpontokat.

Paraméterek és fejlécek – minden végponthoz meg kell jeleníteni a paramétereket, legyen szó a lekérdezésről vagy a törzsparaméterekről, és ha ez a törzs, akkor ügyeljen arra, hogy meghatározza, milyen típusú törzsparaméter, van sima szöveg, JSON (JavaScript objektum jelölés), űrlapadatok és egyebek. A fejlécek mező egy másik fontos szempont, amelyet szintén dokumentálni kell.

Hibakódok és hibakezelés – az API Dokumentációnak tartalmaznia kell egy listát az összes lehetséges hibakódról, amely meghatározza, hogy az egyes hibakódok mit jelentenek és hogyan kezeljük a hibát, javaslom, hogy az útmutatókban is szerepeljen.

API-verzió- és változásnapló – az API-dokumentáció másik fontos szempontja a verzió- és változásnapló, mivel az API-k verziószámmal vannak ellátva, az API-dokumentáció elavult lesz, ha az API-val együtt nem tud átkerülni az API újabb verziójára.

Támogatás elérhetőségei – Elérhetőségi adatok hozzáadhatók, hogy az esetleges hibákat az azt használók kijavíthassák, vagy akár jobban kiszolgálhassák az ügyfeleket abban az esetben, ha nem értenek egy adott részt.

Ezekkel az API-dokumentációt úgy határozhatjuk meg, mint egyértelmű utasításokat és útmutatókat, amelyek segítik a fejlesztőket, a szervezetvezetést és az üzleti partnereket, hogy megértsék, hogyan működik egy adott API, hogy megkönnyítsék az API-ból származó szolgáltatások fejlesztését és integrálását. Köszönjük, hogy végig odafigyelt.
Ha idáig eljutott, az azt jelenti, hogy rövid időn belül biztos API-dokumentációs mérnök lesz, és megvan a következő lépésem a következő cikkemben: „Eszközök az API-dokumentációhoz " ott találkozunk