Warunki Swagger i OpenAPI

Kiedy pisałem poprzedni artykuł, który nigdy nie został opublikowany, zdałem sobie sprawę, że wielu nie rozumie różnicy między pojęciami Swagger i OpenAPI (OAS) . Ludzie używają obu terminów zamiennie. Nie winię ich, ponieważ miałem te same wątpliwości.

Swagger pozwala opisać strukturę twoich interfejsów API, aby maszyny mogły je odczytać.
— SwaggerIO

Jeśli spróbujesz wyszukać w Google Swagger lub OpenAPI , w większości przypadków trafisz na SwaggerIO , oficjalną witrynę Swagger. Jeśli mnie pytasz, strona internetowa przesłaniała cel Swaggera od pierwszego dnia. Jednak nie celowo. Informacji nie brakuje, po prostu nie są one przedstawione w jasny i zwięzły sposób.

Specyfikacja OpenAPI (OAS) definiuje standardowy, niezależny od języka interfejs API RESTful, który umożliwia zarówno ludziom, jak i komputerom odkrywanie i rozumienie możliwości usługi bez dostępu do kodu źródłowego, dokumentacji lub poprzez kontrolę ruchu sieciowego.
— SwaggerIO

Obecnie istnieje wiele artykułów na ten temat, dlatego o wiele łatwiej jest ustalić różnicę, ale nadal można znaleźć pisma, które przeplatają terminy. SwaggerIO promuje Swagger jako zestaw narzędzi , a OpenAPI jako specyfikację. Można powiedzieć, że Swagger służy do tworzenia specyfikacji OpenAPI . Zasadniczo to stwierdzenie nie jest błędne, ale nie jest całą prawdą.

Wykorzystanie warunków

Zwykle programiści używają terminu Swagger przynajmniej w dwóch kontekstach:

• opisać zestaw narzędzi do implementacji specyfikacji. Niektóre narzędzia to Swagger Editor, Swagger UI, Swagger Codegen itp. Jest to ekosystem.
• opis specyfikacji wersji 2.*.*

Deweloperzy używają terminu Specyfikacja OpenAPI 3 głównie w jednym kontekście:

• opisanie specyfikacji wersji 3.*.*. Społeczność odnosi się do OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification itp. Przyjęli OpenAPI 3 jako następcę specyfikacji Swagger 2.

Swagger i OpenAPI są bliskimi przyjaciółmi nie bez powodu. Historia jest tutaj kluczowym składnikiem.

Firma SmartBear utrzymuje Swaggera. W listopadzie 2015 r. Linux Foundation ogłosiła, że ​​wraz ze SmartBear, Google, Microsoft, Paypal i kilkoma innymi firmami tworzy nową organizację, OpenAPI Initiative. Podstawowym zadaniem inicjatywy było rozszerzenie specyfikacji Swaggera.

Kilka miesięcy później inicjatywa zmieniła nazwę Swagger na specyfikację OpenAPI. Inicjatywa sklonowała kod do nowego repozytorium. Od tego momentu osoby używały obu terminów w różnych kontekstach.

Ostatnie słowo

Swagger był kiedyś uniwersalnym, specyfikacją i zestawem narzędzi. Dziś Swagger to zestaw narzędzi. OpenAPI to specyfikacja. Otóż ​​to.

Miło jest znać różnicę. Jednak niezależnie od tego, jakiego terminu użyjesz, druga strona cię zrozumie – w końcu tylko to się liczy.