Mi az OpenAPI-specifikáció?

Az OpenAPI-specifikáció, korábbi nevén Swagger az API különböző aspektusait ismerteti. Az OpenAPI-specifikáció (specifikáció) az API végpontjait, paramétereit és válaszait írja le. Az OpenAPI-specifikációk YAML-ben vagy JSON-ban vannak megírva, és az eszközök dokumentációt, teszteseteket és ügyfélkódtárakat hoznak létre. OpenAPI-specifikációval az API-készítők gondoskodhatnak arról, hogy api-juk pontosan le legyen írva, hozzáférhetőbb és könnyebben integrálható legyen az alkalmazások és szolgáltatások széles körében.

Ezért érdemes megfontolnia egy OpenAPI-specifikáció használatát az API-hoz:

• API dokumentálása szabványosított módon. Az API-specifikációk dokumentálása egységes és ember által olvasható formátumban.
• Hozzon létre egy ügyféloldali SDK-t. Az olyan eszközökkel, mint a Kiota , automatizálhatja az ügyfélkódtárak létrehozásának automatizálását különböző programozási nyelveken.
• Hozzon létre egy minta API-t. Hozzon létre modellkiszolgálókat az API-specifikáció alapján, amely segít a fejlesztés korai szakaszában, amikor a tényleges API még nincs implementálva.
• Az együttműködés javítása. Biztosítson különböző csapatokat (előtér, háttérrendszer, minőségbiztosítási) az API képességeinek és korlátainak világos megértéséhez, amely segít az új csapattagoknak a gyors felzárkózással.
• Egyszerűsítse a tesztelést és az ellenőrzést. Automatizálhatja az API-kérések és válaszok hitelesítését a specifikációval szemben, ami megkönnyíti az eltérések azonosítását.
• Integrálható az API felügyeleti eszközeivel. Az API-k egyszerűen integrálhatók, üzembe helyezhetők és monitorozhatnak számos API felügyeleti eszközzel és átjáróval, például az Azure API Centerrel és az Azure API Managementtel.
• Egyszerűsítse az API-átjárók konfigurálásának folyamatát. OpenAPI-specifikációk használatával konfigurálhatja az API-átjárókat, és automatizálhatja az olyan feladatokat, mint az útválasztás, az átalakítások és a forrásközi erőforrás-megosztási beállítások.

OpenAPI-specifikációk használatával jól megtervezett és következetesen dokumentált API-kat hozhat létre. Emellett karbantarthatóbbak és könnyebben használhatók mind belső, mind külső felhasználók számára.

Még nincs OpenAPI-specifikációd?

A már létező API-k specifikációinak kézzel történő írása időt vesz igénybe, és a specifikáció eltér attól, amit az API ténylegesen csinál. Egy másik lehetőség, hogy rögzíteni lehet, amit az API visszaad, és abból létre lehet hozni a specifikációt.

Approach	Mit kap meg?	Mit kell figyelni?
Írja kézzel	Leírások és példák teljes körű irányítása	Időbe telik, és eltér a valódi API-tól
Generálja kódannotációkból	A kóddal szinkronban maradó specifikáció	Hozzá kell férnie az API kódhoz, és a keretrendszernek támogatnia kell azt
Generálja a rögzített forgalmi adatokból	Bármely meghívható API specifikációja, beleértve a nem az Ön tulajdonában lévő API-kat is	Csak a rögzített kérésekre vonatkozik, ezért használja az API szükséges részeit

Dev Proxy rögzíti az alkalmazás és egy API közötti kéréseket és válaszokat, és létrehoz belőlük egy OpenAPI-specifikációt. A lépésekért lásd: OpenAPI-specifikáció létrehozása.

Következő lépés

OpenAPI-specifikáció létrehozása