Co je specifikace OpenAPI?

Specifikace OpenAPI, dříve označovaná jako Swagger, popisuje různé aspekty rozhraní API. Specifikace OpenAPI (specifikace) popisuje koncové body, parametry a odpovědi rozhraní API. Specifikace OpenAPI jsou napsané v YAML nebo JSON a používají je nástroje k vygenerování dokumentace, testovacích případů a klientských knihoven. Díky specifikaci OpenAPI můžou tvůrci rozhraní API zajistit, aby jejich rozhraní API bylo přesně popsáno, přístupnější a snadněji se integrovalo napříč širokou škálou aplikací a služeb.

Tady je důvod, proč byste měli zvážit použití specifikace OpenAPI pro vaše rozhraní API:

• Zdokumentovat rozhraní API standardizovaným způsobem Zdokumentovat specifikaci rozhraní API v konzistentním a čitelném formátu.
• Vygenerujte klientskou sadu SDK. Pomocí nástrojů, jako je Kiota , můžete automatizovat generování klientských knihoven v různých programovacích jazycích.
• Vytvořte napodobení rozhraní API. Vytváření napodobených serverů na základě specifikace rozhraní API, což vám pomůže v počátečních fázích vývoje, když skutečné rozhraní API ještě není implementováno.
• Vylepšení spolupráce. Poskytněte různým týmům (front-end, back-end, kontrolu kvality) jasný přehled o možnostech a omezeních rozhraní API, což pomáhá novým členům týmu rychle dohnat.
• Zjednodušení testování a ověřování Automatizujte ověřování požadavků rozhraní API a odpovědí podle specifikace, což usnadňuje identifikaci nesrovnalostí.
• Integrace s nástroji API Management Snadná integrace, nasazení a monitorování rozhraní API s mnoha nástroji a bránami služby API Management, jako je Azure API Center a Azure API Management.
• Zjednodušení konfigurace brány rozhraní API Pomocí specifikací OpenAPI můžete konfigurovat brány rozhraní API a automatizovat úlohy, jako jsou směrování, transformace a nastavení sdílení prostředků mezi zdroji.

Pomocí specifikací OpenAPI můžete vytvářet rozhraní API, která jsou dobře navržená a konzistentně zdokumentovaná. Jsou také snadněji udržovatelné a snadněji se používají interně i externími spotřebiteli.

Ještě nemáte specifikaci OpenAPI?

Ruční psaní specifikace pro rozhraní API, které už existuje, nějakou dobu trvá a posunuje se od toho, co rozhraní API skutečně dělá. Další možností je zaznamenat, co rozhraní API vrátí, a vygenerovat z toho specifikace.

Approach	Co získáte	Co sledovat
Napište to ručně	Úplná kontrola nad popisy a příklady	Trvá to nějakou dobu a odchyluje se to od skutečného API.
Vygenerujte ho z anotací v kódu.	Specifikace, která zůstane synchronizovaná s vaším kódem	Potřebujete přístup ke kódu rozhraní API a framework to musí podporovat.
Vygenerujte ho ze zaznamenaného provozu.	Specifikace pro libovolné rozhraní API, které můžete volat, včetně těch, které nevlastníte	Pokrývá pouze požadavky, které jste zaznamenali, takže si procvičte části rozhraní API, které potřebujete.

Dev Proxy zaznamenává požadavky a odpovědi mezi vaší aplikací a rozhraním API a generuje z nich specifikaci OpenAPI. Postup najdete v tématu Vygenerování specifikace OpenAPI.

Další krok

Vygenerování specifikace OpenAPI