Co to jest specyfikacja interfejsu OpenAPI?

Specyfikacja interfejsu OpenAPI, wcześniej znana jako Swagger, opisuje różne aspekty interfejsu API. Specyfikacja interfejsu OpenAPI (spec) opisuje punkty końcowe, parametry i odpowiedzi interfejsu API. Specyfikacje interfejsu OpenAPI są zapisywane w formacie YAML lub JSON i są używane przez narzędzia do generowania dokumentacji, przypadków testowych i bibliotek klienckich. Dzięki specyfikacji interfejsu OpenAPI konstruktorzy interfejsów API mogą zagwarantować, że ich interfejs API jest dokładnie opisany, bardziej dostępny i łatwiejszy do zintegrowania w wielu aplikacjach i usługach.

Oto dlaczego warto rozważyć posiadanie specyfikacji OpenAPI dla swojego API:

• Dokumentowanie interfejsu API w ustandaryzowany sposób. Dokumentowanie specyfikacji interfejsu API w spójnym i czytelnym dla człowieka formacie.
• Generowanie zestawu SDK klienta. Użyj narzędzi, takich jak Kiota , aby zautomatyzować generowanie bibliotek klienckich w różnych językach programowania.
• Utwórz testowe API. Tworzenie pozorowanych serwerów na podstawie specyfikacji interfejsu API, która pomaga we wczesnych etapach programowania, gdy rzeczywisty interfejs API nie jest jeszcze zaimplementowany.
• Ulepszanie współpracy. Zapewnienie różnym zespołom (frontendowi, backendowi, kontroli jakości) jasnego zrozumienia możliwości i ograniczeń interfejsu API pomaga nowym członkom zespołu szybko się wdrożyć.
• Upraszczanie testowania i walidacji. Automatyzowanie walidacji żądań interfejsu API i odpowiedzi względem specyfikacji, co ułatwia identyfikowanie rozbieżności.
• Integracja z narzędziami zarządzania API. Łatwe zintegrowanie, wdrażanie i monitorowanie interfejsów API za pomocą wielu narzędzi do zarządzania API i bram, takich jak Azure API Center i usługa Azure API Management.
• Uprość konfigurację bramy interfejsu API. Użyj specyfikacji interfejsu OpenAPI, aby skonfigurować bramy interfejsu API i zautomatyzować zadania, takie jak routing, przekształcenia i ustawienia udostępniania zasobów między źródłami.

Korzystając ze specyfikacji interfejsu OpenAPI, można tworzyć interfejsy API, które są dobrze zaprojektowane i spójnie udokumentowane. Są one również bardziej konserwowalne i łatwiejsze w użyciu zarówno wewnętrznie, jak i przez konsumentów zewnętrznych.

Nie masz jeszcze specyfikacji interfejsu OpenAPI?

Ręczne pisanie specyfikacji dla istniejącego API zajmuje trochę czasu i odbiega od tego, co API naprawdę robi. Inną opcją jest zapisanie tego, co zwraca interfejs API, i wygenerowanie na tej podstawie specyfikacji.

Approach	Co otrzymujesz	Co należy obejrzeć
Napisz go ręcznie	Pełna kontrola nad opisami i przykładami	Zajmuje to trochę czasu i odbiega od rzeczywistego API
Wygeneruj to na podstawie adnotacji w kodzie	Specyfikacja, która pozostaje zsynchronizowana z kodem	Potrzebujesz dostępu do kodu interfejsu API, a framework musi go obsługiwać
Wygeneruj to na podstawie zarejestrowanego ruchu	Specyfikacja dla dowolnego interfejsu API, który można wywołać, w tym takiego, którego nie jesteś właścicielem	Obejmuje ona tylko zarejestrowane żądania, więc przećwicz potrzebne części interfejsu API

Dev Proxy rejestruje żądania i odpowiedzi między aplikacją a interfejsem API i generuje na ich podstawie specyfikację interfejsu OpenAPI. Aby uzyskać instrukcje, zobacz Wygeneruj specyfikację OpenAPI.

Następny krok

Generowanie specyfikacji interfejsu OpenAPI