Vad är en OpenAPI-specifikation?

OpenAPI-specifikationen, som tidigare kallades Swagger, beskriver olika aspekter av ett API. En OpenAPI-specifikation (specifikation) beskriver API:ets slutpunkter, parametrar och svar. OpenAPI-specifikationer skrivs i YAML eller JSON och används av verktyg för att generera dokumentation, testfall och klientbibliotek. Genom att ha en OpenAPI-specifikation kan API-byggare se till att deras API beskrivs korrekt, är mer tillgängligt och enklare att integrera i en mängd olika program och tjänster.

Därför bör du överväga att ha en OpenAPI-specifikation för ditt API:

• Dokumentera ett API på ett standardiserat sätt. Dokumentera en API-specifikation i ett konsekvent och läsbart format.
• Generera ett SDK för klient. Använd verktyg som Kiota för att automatisera genereringen av klientbibliotek på olika programmeringsspråk.
• Skapa ett falskt API. Skapa falska servrar baserat på API-specifikationen, vilket hjälper dig under de tidiga utvecklingsfaserna när det faktiska API:et ännu inte har implementerats.
• Förbättra samarbetet. Ge olika team (klientdel, serverdel, QA) en tydlig förståelse för API:ets funktioner och begränsningar, vilket hjälper nya teammedlemmar att snabbt komma ikapp.
• Förenkla testning och validering. Automatisera valideringen av API-begäranden och svar mot specifikationen, vilket gör det enklare att identifiera avvikelser.
• Integrera med API-hanteringsverktyg. Integrera, distribuera och övervaka dina API:er enkelt med många API-hanteringsverktyg och gatewayer, till exempel Azure API Center och Azure API Management.
• Förenkla konfigurationen av API Gateway. Använd OpenAPI-specifikationer för att konfigurera API-gatewayer och automatisera uppgifter som routning, transformeringar och resursdelningsinställningar mellan ursprung.

Genom att använda OpenAPI-specifikationer kan du skapa API:er som är väl utformade och konsekvent dokumenterade. De är också mer underhållsbara och enklare att använda både internt och av externa konsumenter.

Har du ingen OpenAPI-specifikation än?

Det tar tid att skriva en specifikation för hand för ett API som redan finns, och den glider bort från vad API:et faktiskt gör. Ett annat alternativ är att registrera vad API:et returnerar och generera specifikationen från det.

Approach	Vad du får	Vad du ska titta efter
Skriv det för hand	Fullständig kontroll över beskrivningar och exempel	Det tar tid och avviker från det verkliga API:et
Generera den från kodannoteringar	En specifikation som förblir synkroniserad med din kod	Du behöver åtkomst till API:ets kod och ramverket måste stödja det
Generera den från inspelad trafikdata	En specifikation för alla API:er som du kan anropa, inklusive de som du inte äger	Den omfattar endast de begäranden som du har registrerat, så använd de delar av API:et som du behöver

Dev Proxy registrerar begäranden och svar mellan din app och ett API och genererar en OpenAPI-specifikation från dem. Anvisningar finns i Generera en OpenAPI-specifikation.

Nästa steg

Generera en OpenAPI-specifikation