Szia! API (Active Pharmaceutical Ingredient) szállító vagyok, és ma arról szeretnék beszélgetni, hogyan dokumentálhatok egy API-t OpenAPI használatával. Ez rendkívül fontos a munkánkban, mivel a világos dokumentáció megnövelheti vagy megzavarhatja API-jaink sikerét.
Először is értsük meg, mi az az OpenAPI. Az OpenAPI egy nyílt szabványú specifikáció a RESTful API-k leírására. Módot biztosít az API végpontjainak, műveleteinek, bemeneti és kimeneti adatainak, valamint biztonsági követelményeinek gépi olvasható formátumban történő meghatározására. Ez azt jelenti, hogy más fejlesztők könnyen megérthetik és integrálhatják az API-jainkat alkalmazásaikba.
Miért fontos az API-k OpenAPI-val történő dokumentálása?
API beszállítóként egy csomó nagyszerű termékünk van, mint plMemantin-hidroklorid 丨CAS 41100 - 52 - 1,Dezoximetazon 丨CAS 382-67-2, ésGlutation丨CAS 70-18-8. Ahhoz, hogy ügyfeleink könnyebben hozzáférhessenek ezekhez az API-khoz, és használatuk is könnyebben elérhetők, elengedhetetlen a megfelelő dokumentáció.
Ha az API-jainkat OpenAPI-val dokumentáljuk, az több szempontból is segít. Egyrészt lehetővé teszi számunkra, hogy egyértelműen kommunikáljunk ügyfeleinkkel arról, mire képesek API-jaink. Pontosan láthatják, hogy milyen végpontok állnak rendelkezésre, milyen paramétereket kell átadniuk, és milyen válaszokra számíthatnak. Ez csökkenti a kérdések és a félreértések számát, ami viszont időt takarít meg nekünk és ügyfeleinknek egyaránt.
További előnye, hogy elősegíti az átjárhatóságot. Mivel az OpenAPI nyílt szabvány, sok eszköz és keretrendszer támogatja. Ez azt jelenti, hogy a fejlesztők különféle eszközöket használhatnak klienskód generálására, API-ink tesztelésére, és még az API-struktúra megjelenítésére is. Ez megkönnyíti számukra az API-ink integrálását meglévő rendszereikbe.
Az OpenAPI dokumentációjának első lépései
Az API OpenAPI használatával történő dokumentálásának első lépése az API-val kapcsolatos alapvető információk meghatározása. Ez magában foglalja az API címét, leírását, verzióját és kapcsolatfelvételi adatait. Ezt úgy tekintheti, mint az API "metaadatait". Például mondhat valamit:
openapi: 3.0.0 info: title: API for Pharmaceutical Ingredients leírás: Ez az API hozzáférést biztosít különböző gyógyszerhatóanyagainkkal kapcsolatos információkhoz. verzió: 1.0.0 kapcsolattartó: név: API Támogatási e-mail: support@example.comEzután meg kell határoznia azokat a szervereket, amelyeken az API található. Ez megmondja a fejlesztőknek, hogy ténylegesen hol intézhetnek kéréseket az API-hoz. Több kiszolgálót is megadhat, például egy éles szervert és egy tesztkiszolgálót.
szerverek: - url: https://api.example.com/v1 leírás: Éles kiszolgáló - url: https://teszt-api.example.com/v1 leírás: TesztszerverAPI útvonalak és műveletek meghatározása
Az OpenAPI-dokumentumok lényege az API-útvonalak és -műveletek meghatározása. Az elérési út egy adott végpontot jelöl az API-ban, a művelet pedig az adott végponton végrehajtható művelet, például GET, POST, PUT vagy DELETE.
Tegyük fel, hogy van egy API-nk, amely információkat nyújt gyógyszerkészítményeinkről. Lehet, hogy van egy ilyen utunk/összetevőkhogy megkapja az összes elérhető összetevő listáját.
elérési utak: /összetevők: get: összefoglaló: Az összes gyógyszerészeti összetevő listája leírás: Az általunk kínált összes gyógyszerhatóanyag listáját adja vissza. válaszok: '200': leírás: Összetevők listája tartalom: alkalmazás/json: séma: típus: tömbelemek: típus: objektum tulajdonságai: név: típus: karakterlánc cas_number: típus: karakterláncEbben a példában egy GET műveletet definiáltunk a/összetevőkútvonal. Az összefoglaló és leírás további információkat nyújt a műveletről. A válaszok szakasz meghatározza, hogy az API mit ad vissza, ha a művelet sikeres (200-as állapotkód). Ebben az esetben az objektumok JSON-tömbjét adja vissza, ahol minden objektum egy összetevőt képvisel névvel és CAS-számmal.
Bemeneti paraméterek kezelése
Sok API-művelethez bemeneti paraméterek szükségesek. Ezek lehetnek lekérdezési paraméterek (az URL-ben elküldve), elérési út paraméterek (az URL részei), vagy a kérelem törzsparaméterei (a kérés törzsében elküldve).
Tegyük fel, hogy egy adott összetevőről a CAS-szám alapján szeretnénk információt szerezni. Ehhez megadhatunk egy path paramétert.
elérési utak: /ingredients/{cas_number}: get: summary: Információk lekérése egy adott összetevő leírásáról: Részletes információkat ad vissza egy összetevőről a CAS-száma alapján. paraméterek: - név: cas_number in: útvonal leírása: A szükséges összetevő CAS-száma: true séma: típus: karakterlánc válaszok: '200': leírás: Információ az összetevő tartalmáról: application/json: séma: típus: objektum tulajdonságai: név: típus: karakterlánc cas_number: típus: karakterlánc leírása: típus: karakterláncEbben a példában egy elérési út paramétert definiáltunkcas_numbera/összetevők/{cas_number}útvonal. Akívántmező azt jelzi, hogy ezt a paramétert meg kell adni a kéréskor.
Biztonság és hitelesítés
A biztonság minden API kulcsfontosságú szempontja. Az OpenAPI lehetővé teszi az API-műveletek biztonsági követelményeinek meghatározását. Megadhat például API-kulcsokat, OAuth 2.0-t vagy alapszintű hitelesítést.
Például, ha az API-nk API-kulcsokat használ a hitelesítéshez, akkor ezt a következőképpen határozhatjuk meg:
összetevők: biztonságSémák: api_key: típus: apiKey neve: X - API - Kulcs: fejléc biztonsága: - api_key: []Ebben a példában egy biztonsági sémát definiáltunkapi_keyamely a beküldött API-kulcsot használjaX - API - Kulcsfejléc. Abiztonságszakasz a dokumentum felső szintjén azt jelzi, hogy az API minden műveletéhez szükség van erre az API-kulcsra a hitelesítéshez.
Az OpenAPI-dokumentum érvényesítése és tesztelése
Miután létrehozta az OpenAPI-dokumentumot, fontos ellenőrizni, hogy megfelel-e az OpenAPI-specifikációnak. Számos online eszköz áll rendelkezésre, amelyek segíthetnek ebben. Eszközökkel is létrehozhat ügyfélkódot az OpenAPI-dokumentumból, és tesztelheti az API-t.
A tesztelés kulcsfontosságú annak biztosításához, hogy az API a várt módon működjön. Az olyan eszközökkel, mint a Postman vagy a cURL, kéréseket küldhet az API-nak, és ellenőrizheti a válaszokat. Ha teszteli az API-t különböző bemeneti paraméterekkel és forgatókönyvekkel, már korán felismerheti a hibákat vagy problémákat.
Következtetés és cselekvésre ösztönzés
Az API OpenAPI-val történő dokumentálása hatékony módja annak, hogy API-ját elérhetőbbé és felhasználóbarátabbá tegye. API beszállítóként segít jobban kiszolgálni ügyfeleinket és előmozdítani termékeink használatát, mint plMemantin-hidroklorid 丨CAS 41100 - 52 - 1,Dezoximetazon 丨CAS 382-67-2, ésGlutation丨CAS 70-18-8.
Ha többet szeretne megtudni API-inkról, vagy kérdése van a dokumentációval kapcsolatban, forduljon bizalommal. Mindig örömmel vitatjuk meg a lehetséges partnerségeket, és segítünk API-jainknak a projektjeibe való integrálásában. Akár egy kis kezdő vállalkozás, akár egy nagy gyógyszeripari vállalat, API-jaink értékes információkkal szolgálhatnak kiváló minőségű gyógyszerészeti összetevőinkről.
Hivatkozások
- OpenAPI specifikációs dokumentáció
- Swagger.io – Eszközök és erőforrások az OpenAPI-hoz
- Postman dokumentáció az API teszteléséhez
