Az api dokumentációt a raml-el írjuk
- 24.08.15 11:51 •
- yuhenobi •
- # 265337 •
- Habrahabr •
- 37 •
- 8709
- ugyanaz, mint Forbes, csak jobb.
Az API-kkal való együttműködés sok szempontból attól függ, hogy a dokumentáció hogyan lett megírva és keretezve. Most dolgozunk az API-k leírásának szabványosításán és egyesítésén, és a dokumentációs kérdések különösen fontosak számunkra.
Hosszú keresés után úgy döntöttünk, hogy a dokumentációt RAML formátumban készítjük el. Ez a REST API leírásának speciális szakasza. A képességekről és előnyeikről ebben a cikkben foglalkozunk.
Miért van RAML?
Az API dokumentálása? Ez a kérdés nem olyan egyszerű, mint első pillantásra.
Az első és legegyszerűbb lehetőség, amelyre emlékeztetni kell, hogy leírja az API-t egy egyszerű szöveges dokumentum formájában. Szóval sokan (köztük nagyon jól ismert vállalatok). Ezt a módszert többször is használtuk. Az egyszerűség kedvéért a következő hátrányai vannak:
- nehéz naprakészen tartani a szöveges dokumentumokat;
- az API gyakran verbális leírása nem elég világos;
- A "verbális" dokumentáció alkalmazásának köre nagyon korlátozott (például az alapján lehetetlen interaktív tesztoldal létrehozása).
A dokumentációs folyamat egyszerűsítése érdekében speciális eszközöket és szolgáltatásokat használhat. Jellemzően a leírást alapul véve szabványosított formában - általában a JSON vagy a Markdown.
Ezeknek a formátumoknak egyike sem alkalmas dokumentáció írására. A JSON-t eredetileg az interneten történő adatcserére hozták létre. Ha más célokra használja, akkor a "mancsok" használatához kell fordulnia - például a $ jelzéssel kezdődő egyedi mezőkből. Ezenkívül a JSON formátumú leírások készítése kézzel is meglehetősen rutinszerű és fárasztó (különösen nagy méretű leírások esetén).
Természetesen a YAML sokkal kényelmesebb, mint a JSON. De használata bizonyos nehézségeket okoz. Az a tény, hogy az API leírások mindig ismétlődő elemek (pl választ a rendszer, amely lehet azonos a különböző típusú HTTP-kérések), amelyet minden alkalommal jelentkezik kézzel. Most, ha egyszer és örökre megírhatja őket egy külön fájlba, és szükség esetén hivatkozni rá ... De sajnos eddig ez nem lehetséges.
A RAML kétségtelen előnyei:- egyszerű és logikus szintaxis a YAML formátum alapján;
- az örökség támogatása és a külső specifikációs fájlok csatlakoztatásának képessége.
További előnye az online dokumentáció nagyszámú konverterének, feldolgozójának és generátorának elérhetősége. Az alábbiakban néhányat tárgyalunk, de most nézzük át a RAML-szintaxis funkcióinak áttekintését.
Rövid bevezetés a RAML-hez
A dokumentum szerkezete
A RAML specifikációs fájlja a következő szerkezeti elemekből áll:
- bevezető rész ("sapka");
- biztonsági rendszer;
- profilok leírása;
- tárgyak és módszerek leírása;
- a válaszok leírása.
Nézzük ezeket az elemeket részletesebben.
prodrome
Minden egyes RAML dokumentum egy bevezetővel kezdődik, amely négy szükséges elemet tartalmaz:
- RAML verzió;
- a dokumentum neve;
- URI, amelyhez az API rendelkezésre áll;
- A dokumentációban leírt API változata.
Ez így néz ki:
A bevezető rész számos további információt is tartalmazhat - például az API-val való kommunikációhoz használt protokoll adatai:
A bevezetőben a dokumentációs fájl metaadatait is megírhatja:
Biztonsági ábrák
A következő részlet a következő információkat tartalmazza:
Ez segít a dokumentációs folyamat felgyorsításában, a szükségtelen ismétlés elkerülésében és a dokumentáció kisebb méretűvé tételében.
További információ a biztonsági rendszerekről és itt talál konkrét példákat (szakasz Biztonság).
Tárgyak és módszerek
Az alábbiak a fő objektumok és útvonalak, valamint az ezekkel az objektumokkal használt HTTP módszerek:
A fenti példában leírtak egy API-t, amelynek segítségével dokumentumokkal dolgozhat. Dokumentumokat letölthetünk a helyi gépre (GET), megváltoztathatjuk a meglévő dokumentumokat (PUT) és tölthetünk be újakat (POST). Minden egyes dokumentumhoz () a következő műveleteket is végrehajthatjuk: letöltés a helyi gépre (GET) és törlés (DELETE).
Az ezzel vagy az eljárással használt HTTP-fejléceket a fejlécek tulajdonsága írja le, például:
Jegyezze fel a szükséges tulajdonságot: jelzi, hogy a fejléc szükséges-e (igaz) vagy opcionális (hamis).
A tárgyak és módszerek leírásában számos további paraméter használható. Tekintsük a következő példát:
Itt azt kell mondanunk, hogy az egyes dokumentumok, amelyekhez hozzáférés áll rendelkezésre az API, saját azonosító kódját, mint egy húr (típus: string), valamint leírja a formátum a kód reguláris kifejezések segítségével.
A leírás, a típus és a minta tulajdonságai szintén használhatók a módszer leírása során, például:
Minden egyes módszer esetében egyedi biztonsági rendszert írhat:
Lekérdezési paraméterek
A dokumentáció minden egyes módjára megadhatja a lekérdezésben használt lekérdezési paramétereket. Minden egyes lekérdezési paraméter esetében a következő jellemzők vannak megadva: név, típus, leírás és példa:
A leírások felesleges ismétlésének elkerülése érdekében a RAML olyan jellemzőket használ, amelyeket a dokumentum bevezető részében írnak elő:
A jövőben a profil elérhető bármilyen módszerrel:
A felhasználás profiljairól és tulajdonságairól további részletek találhatók a hivatalos dokumentációban (Szakaszok jellemzői).
A válasz leírása
A válasz leírásán fel kell tüntetni a kódot. A leírásban is hozzáadhat egy sémát (séma) - a válaszba beírandó paraméterek felsorolását és típusát. Adhat példát egy adott válaszra (példa).
A válaszsémák különálló .yml vagy .raml fájlokban menthetők el, és a dokumentáció más részeiben hivatkozhatnak rájuk:
Vizualizáció és dokumentáció generálása
RAML2HTML és más konverterek
Annak ellenére, hogy a RAML egy viszonylag új formátum, elegendő átalakítót és elemzőt fejlesztettek ki számára. Egy példa a ram2htmtl. generál egy statikus HTML oldalt a RAML leírás alapján.
Telepítve van az npm csomagkezelő használatával:
Egy RAML fájl HTML-be konvertálásához egyszerűen futtasson egy egyszerű parancsot:
API tervező
Az oldal jobb oldalán automatikusan létrejön az interaktív dokumentáció. Itt is tesztelheti az API-t: erre a célra egyszerűen bontsa ki a lekérdezés leírását, és kattintson a Próbálja meg.
Az API Designer lehetővé teszi, hogy RAML fájlokat töltsön be a helyi gépről. Támogatja a Swagger API leírás fájlok importálását.
Ezenkívül a Designer API tárolja a vizsgálati lekérdezések statisztikáit az API-val szemben.
Konzol API
Az API konzol egy hasznos eszköz, amelyet ugyanaz a cég fejlesztett ki, mint a MuleSoft. Ennek segítségével közvetlenül a böngészőben dokumentálhatja az API-t. A specifikációs fájlok letölthetők a helyi számítógépről vagy külső forráshoz kapcsolódhatnak:
Az API konzol számos mintafájlt tartalmaz, amelyek a népszerű internetes szolgáltatások API-jának leírásai: Twitter, Instagram, Box.Com, LinkedIn. Megpróbáltunk dokumentációt készíteni az egyik fenékrészen - elég szépnek tűnik:
A kimeneten kapott dokumentáció interaktív: ebben nemcsak az API-leírás olvasható, hanem tesztkérdések is végrehajthatók.
következtetés
Csak a regisztrált felhasználók vehetnek részt a felmérésben. Jelentkezzen be. kérem.
Minél jobb? Válaszolok a pontokra?
1. A leírások sokkal egyszerűbb és logikusabb szintaxisa.
2. Lehet, hogy festeni a dokumentációt még sok más lehetőség, mint az azonos hetvenkedő és ami a legfontosabb, csinálni egy egyszerű és felhasználóbarát kialakítást (összehasonlítani az azonos leírást a biztonsági rendszerek vagy a query-paraméterek).
3. Kiterjesztett (ugyanazon swaggerrel összehasonlítva) a beillesztés és öröklés használatát, így a dokumentáció kompaktabb és elegánsabb.
Az egyetlen dolog, amit a RAML jelenleg elveszíti a Swagger-et, a nem megfelelő számú eszköz, amelyet a közösség fejleszt. De ez egy jövedelmes üzlet.
A RAML számára léteznek olyan eszközök, amelyek automatikusan létrehozzák a meglévő API (ebben a formátumban) leginkább megfelelő dokumentációt ebben a formátumban?
Aktívan használom a formátumot, minden, ami a cikkben olvasható a RAML számára a bluetooth. Az eredmény egy gyönyörű és felhasználóbarát, de egy író api tervét méret kicsit koryavenko, nagyon kellemetlen, például követnek chur szigorú követelmények a helyek száma és a lapok: a paraméterek listáját - ez két Taba, valami mást - négy Taba, stb .D. Úgy tűnik, egy kicsit felesleges, mert nyilvánvaló, hogy elemezni, és minden kiderül.
Számunkra PHP-ben a projekt API leírása a WSDL-ben, ez a leírás működik és az elsődleges érvényesítéshez. A dokumentáció az XSLT WSDL-ki transzformációval érhető el. A megközelítés jól bizonyult. De a RAML környékén található cikkekben leírt eszközök lenyűgözőek.