Czym jest OpenAPI?

Specyfikacja OpenAPI (OAS) jest to standard wykorzystywany do opisu API. OAS jest niezależna od języka programowania. Standard jest łatwy do interpretacji i zrozumienia przez ludzi i komputery. API zgodne z OpenAPI definiujemy w YAML lub JSON.

W dalszej części artykuły będę odwoływał się do standardu OpenAPI w wersji 3.0.3 (https://spec.openapis.org/oas/v3.0.3) . Z najnowszą wersją możesz zapoznać się na stronie standardu OpenAPI (https://www.openapis.org/) .

Specyfikacja OpenAPI określa strukturę obiektów, ich typ, opis czy wymagalność. Zgodnie ze specyfikacją OpenAPI minimalna definicja API ma postać

Zajrzyjmy jeszcze do specyfikacji, aby przeanalizować jak to odczytać.

W specyfikacji https://spec.openapis.org/oas/v3.0.3 możemy znaleźć definicję głównego obiektu OpenAPI Object.

Wymagane pola to:

• openapi, który jest typu string
• info, typu Info
• paths, typu Paths

Przeanalizujmy zatem definicję obiektu Info.

Wymagane pola w Info to:

• title, typu string
• version, typu string

Spójrzmy jeszcze na definicję Paths.

Zgodnie z opisem Paths może być puste.

Zatem minimalna postać definicji API zgodna ze standardem OpenAPI ma postać

Projektowanie API poprzez analizę ręczną specyfikacji jest czasochłonne, dlatego warto wykorzystać jedno z narzędzi, które podpowiada składnię, waliduje poprawność przygotowanego dokumentu oraz wizualizuje zaprojektowane API.

Najpopularniejszym narzędziem służącym do tego jest Swagger.

Do czego służy Swagger?

Swagger (https://swagger.io/) jest zestawem narzędzi ułatwiającym projektowanie, implementację, testowanie oraz dokumentowanie API.

Składa się z narzędzi takich jak:

• Swagger Editor – narzędzie ułatwiające projektowanie API zgodnie z OpenAPI
• Swagger UI – narzędzie prezentujące zaprojektowane API
• Swagger Codegen – narzędzie generujące kod klienta oraz serwera na podstawie zaprojektowanego API
• Swagger Hub – platformę do projektowania oraz dokumentowania API przeznaczona dla zespołów i firm

Zaprojektujmy pierwsze API w Swagger Editor (https://editor.swagger.io/) .

W narzędziu Swagger Editor z lewej strony widzimy projekt API w YAML (możemy również wykorzystać JSON) natomiast po prawej stronie wizualizację w Swagger UI.

Zaprojektujmy teraz bardziej skomplikowane API zgodne z OpenAPI.

Projekt API dla domeny Klienta

Zaprojektujemy wspólnie API dla domeny Klienta w przykładowym sklepie.

API będzie umożliwiało:

• pobranie listy klientów
• pobranie szczegółów konkretnego klienta
• dodanie klienta
• modyfikację danych klienta
• usunięcie klienta

W tym celu zaprojektujemy zasób customers.

• /v1/customers – będzie umożliwiał pobranie listy klientów oraz utworzenie nowego klienta
• /v1/customers/{customerId} – będzie umożliwiał pobranie szczegółów konkretnego klienta, aktualizację danych klienta oraz jego usunięcie

Wykorzystamy operacje HTTP GET w celu pobrania, POST w celu utworzenia, PUT do aktualizacji i DELETE do usunięcia zasobów.

Tak zaprojektowany zasób musimy umieścić w sekcji paths zgodnie z OpenAPI.

W kolejnym kroku zaprojektujmy model danych komunikacji, który wykorzystamy w API.

Niech klient określony będzie atrybutami imię, nazwisko, adres email oraz adres klienta, gdzie tylko adres klienta nie jest wymagany. Adres składa się z ulicy, numeru mieszkania, miasta, kodu pocztowego i kraju. Dodatkowo wprowadźmy obiekt lista klientów.

A teraz zaprojektujmy obiekty klienta, adresu oraz listy klientów zgodnie z OpenAPI w sekcji components.

W naszym rozwiązaniu zastosujemy uproszczenie. Gdy pobieramy listę klientów wówczas danych może być bardzo dużo. Popularnym rozwiązaniem poprawiającym wydajność jest wykorzystanie stronicowania wyników. W naszym przykładzie nie wprowadzamy stronicowania.

W kolejnym kroku zaprojektujemy szczegóły wprowadzonych wcześniej operacji.

Rozpocznijmy od operacji pobrania listy klientów. W celu pobrania listy wszystkich klientów nie musimy przekazać w żądaniu żadnych parametrów.

Dla operacji zdefiniowaliśmy możliwe kody odpowiedzi: 200, 400, 401, 500 oraz 503 zgodnie z protokołem HTTP. W przypadku kodu 200 zostanie zwrócona lista klientów. W pozostałych przypadkach kod wraz z informacją o błędzie.

Gdy korzystamy z Swagger Editor wówczas z prawej strony widoczna jest wizualizacja zaprojektowanego zasobu.

W kolejnym kroku zaprojektujemy operację tworzenia nowego klienta. W tym przypadku musimy przekazać w żądaniu dane klienta, który ma zostać utworzony.

W odpowiedzi otrzymamy kod 201, 400, 401, 500 lub 503. Dla kodu 201, który będzie informował o poprawnym utworzeniu klienta dodatkowo przekażemy w odpowiedzi w sekcji headers lokalizację utworzonego zasobu.

Następnie przejdźmy do zaprojektowania pobrania szczegółów klienta. W tym przypadku wprowadzimy parametr customerId, który zostanie przekazany w ścieżce URL. W przypadku sukcesu szczegóły klienta zostaną zwrócone z kodem 200 HTTP.

Kolejnym krokiem jest zaprojektowanie operacji aktualizacji danych klienta. W tym celu wykorzystamy operację PUT. W żądaniu musimy przekazać szczegóły aktualizowanego klienta natomiast w ścieżce URL identyfikator klienta (customerId).

W odpowiedzi otrzymamy kod informujący o statusie operacji: 200, 400, 401, 404, 500 lub 503.

Aby umożliwić usunięcie klienta wykorzystamy operację DELETE. Musimy przekazać identyfikator klienta, którego chcemy usunąć. Podobnie jak dla operacji pobrania szczegółów klienta i aktualizacji klienta zostanie on przekazany w ścieżce URL.

W przypadku operacji usunięcia klienta zostanie zwrócony tylko kod odpowiedzi 200, 400, 401, 404, 500 lub 503.

W naszym API wykorzystamy tokeny JWT w celu zapewnienia bezpieczeństwa. Autoryzację ustawimy globalnie dla wszystkich zasobów. W tym celu dodamy definicję obiektu JwtAuthToken w sekcji compoents oraz w uzupełnimy sekcję security.

Przygotowane przez nas API w narzędziu Swagger zostało zaprezentowane na rysunku poniżej.

Możesz również pobrać zaprojektowane API klikając w LINK .

Dziękuję Ci za przeczytanie artykułu. Gdybyś chciał/chciała podzielić się ze mną swoim komentarzem napisz do mnie na marcin@marcinziemek.com

Jeśli chcesz rozwinąć swoją wiedzę z zakresu projektowania integracji systemów IT, sprawdź moją książkę dostępną pod adresem: https://integracja.marcinziemek.com