OpenAPI and Swagger Ecosystem

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 1 z 19. API napędzają współczesną sieć, ale jak właściwie komunikują się ze sobą bez niekończących się prób i błędów? Potrzebujesz niezawodnego sposobu, aby dokładnie wiedzieć, czego oczekuje serwer i co odeśle, zanim napiszesz choćby jedną linijkę kodu. Tym mechanizmem jest kontrakt API, regulowany przez specyfikację OpenAPI. Specyfikacja OpenAPI to ustandaryzowany, niezależny od języka interfejs dla REST API. Pomyśl o niej jak o projekcie architektonicznym. Kiedy jest dobrze zdefiniowana, zarówno człowiek, jak i maszyna mogą spojrzeć na ten projekt i dokładnie zrozumieć, co robi dany serwis. Nie potrzebują dostępu do kodu źródłowego, nie muszą czytać osobnej dokumentacji w PDF-ie, ani analizować ruchu sieciowego na żywo. Specyfikacja jasno określa dostępne endpointy, dokładne dane wejściowe, których wymagają, oraz precyzyjne struktury zwracanych danych. Jest napisana zwykłym tekstem, w formacie YAML lub JSON, co czyni ją uniwersalnie czytelną zarówno dla zautomatyzowanych narzędzi, jak i dla programistów. Jeśli pracujesz z API, prawdopodobnie słyszałeś termin Swagger. Ludzie często używają nazw Swagger i OpenAPI zamiennie, ale dziś reprezentują one zupełnie inne koncepcje. Pierwotnie sama specyfikacja nosiła nazwę Swagger. W 2015 roku twórcy przekazali specyfikację do Linux Foundation, gdzie oficjalnie zmieniła nazwę na OpenAPI Specification. Obecnie OpenAPI odnosi się wyłącznie do reguł i standardu. Swagger odnosi się do ekosystemu komercyjnych i open-source'owych narzędzi stworzonych przez firmę SmartBear, które implementują te reguły. Na przykład Swagger UI generuje interaktywną dokumentację, a Swagger Editor pomaga w pisaniu plików. Piszesz dokument OpenAPI, ale możesz użyć narzędzi Swagger do jego wizualizacji. To prowadzi nas do prawdziwej mocy tej specyfikacji, czyli podejścia design-first. Bez jasnego kontraktu, tworzenie API zazwyczaj odbywa się liniowo. Zespół backendowy pisze kod, wystawia nowy endpoint, a następnie przekazuje jakąś spisaną dokumentację. Tymczasem zespół frontendowy siedzi bezczynnie, czekając aż backend skończy, żeby móc zacząć podpinanie interfejsu użytkownika. Oto kluczowa sprawa. Kiedy wdrażasz OpenAPI, odwracasz ten proces. Zanim ktokolwiek napisze kod aplikacji, oba zespoły uzgadniają dokument OpenAPI. Ten plik tekstowy staje się ścisłym kontraktem, który eliminuje wszelkie domysły. Zespół backendowy używa go do generowania stubów serwera i walidacji, czy ich implementacja spełnia uzgodnione wymagania. Jednocześnie zespół frontendowy używa dokładnie tego samego dokumentu do generowania mock serwerów. Mogą natychmiast zacząć budować interfejs użytkownika, robiąc requesty sieciowe do symulowanego backendu, który zachowuje się dokładnie tak, jak będzie się zachowywać finalne API. Żaden z zespołów nie blokuje drugiego. Ponieważ ten kontrakt jest odczytywalny maszynowo, trwale rozwiązuje również problem nieaktualnej dokumentacji. Gdy zmienia się wymaganie API, najpierw aktualizujesz plik specyfikacji. Następnie twoje narzędzia automatycznie regenerują dokumentację webową, mock serwery i biblioteki klienta. Dokumentacja i kod pozostają idealnie zsynchronizowane, ponieważ mają jedno wspólne źródło prawdy. Specyfikacja API to nie tylko mechanizm do generowania ładnych stron internetowych; to fundamentalny protokół komunikacyjny dla twoich zespołów inżynierskich, który zamienia ludzkie założenia w wykonywalne reguły. Jeśli podoba ci się podcast i chcesz nas wesprzeć, wyszukaj DevStoriesEU na Patreonie. Dzięki za wysłuchanie. Do usłyszenia następnym razem!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 2 z 19. Pisanie dokumentacji bywa żmudne, ale co by było, gdyby twój kod pisał dokumentację, a dokumentacja pisała kod? Ten dwukierunkowy workflow to główna obietnica open-source'owego ekosystemu Swaggera. Częstym błędem jest myślenie, że musisz wdrożyć cały ekosystem naraz. Wcale nie musisz. Zestaw narzędzi jest całkowicie modułowy. Możesz dobierać pojedyncze komponenty do swoich konkretnych potrzeb w ramach workflow, niezależnie od tego, czy tylko renderujesz istniejącą dokumentację, czy robisz scaffolding zupełnie nowego backendu. Główne narzędzia open-source działają jak pipeline. Projektujesz API w Swagger Editor, wizualizujesz je w Swagger UI i automatyzujesz implementację za pomocą Swagger Codegen. Swagger Editor to miejsce, gdzie zaczyna się projektowanie API. To środowisko przeglądarkowe, w którym piszesz specyfikację OpenAPI w formacie YAML lub JSON. Podczas pisania, edytor na bieżąco waliduje twoją składnię zgodnie z regułami specyfikacji OpenAPI. Jeśli źle umieścisz jakieś pole albo zdefiniujesz nieprawidłowy typ danych, edytor natychmiast pokaże błąd. Oferuje widok split-screen w czasie rzeczywistym, pokazując surowy tekst po jednej stronie i wizualny podgląd po drugiej. Kiedy kontrakt jest poprawny, możesz przejść do automatyzacji za pomocą Swagger Codegen. To narzędzie bierze twój plik specyfikacji OpenAPI i tłumaczy go na działający kod źródłowy. Obsługuje dziesiątki języków i frameworków. Możesz wygenerować server stubs, które dostarczą boilerplate, routing i kontrolery dla twojego backendu. Alternatywnie, możesz wygenerować client SDKs, których aplikacje klienckie używają do interakcji z twoim API bez konieczności pisania własnej logiki requestów HTTP. Jest też Swagger UI. To narzędzie parsuje twoją specyfikację i renderuje ją jako interaktywną, webową stronę z dokumentacją. To coś więcej niż statyczny tekst. Swagger UI generuje pola input i przyciski wywołania bezpośrednio z twoich definicji API. Użytkownicy mogą wpisywać parametry, dołączać tokeny autoryzacyjne, wysyłać prawdziwe requesty HTTP do twoich endpointów API i sprawdzać odpowiedzi prosto w przeglądarce. Wyobraź sobie konkretny workflow łączący te trzy narzędzia. Zaczynasz w Swagger Editor, tworząc szkic specyfikacji dla nowego API do zarządzania użytkownikami. Definiujesz endpointy, payloady requestów i oczekiwane odpowiedzi. Kiedy kontrakt jest gotowy, wrzucasz ten plik do Swagger Codegen, konfigurując go tak, aby wygenerował server stub w Node.js. Codegen automatycznie generuje strukturę katalogów, konfigurację paczek i route handlery. Musisz tylko napisać konkretną logikę biznesową i zapytania do bazy danych wewnątrz tych wstępnie podpiętych kontrolerów. W międzyczasie dajesz ten sam plik specyfikacji OpenAPI swojemu zespołowi QA, zaserwowany przez Swagger UI. Inżynierowie QA nie muszą czytać twojego pliku YAML ani zaglądać do kodu w Node.js. Otwierają stronę Swagger UI, widzą wymagane inputy i od razu zaczynają wysyłać testowe payloady do twojego nowego serwera Node.js. I tu jest kluczowa sprawa. Open-source'owy ekosystem Swaggera zmienia podejście do tworzenia API z pisania kodu backendu i liczenia na to, że dokumentacja pozostanie aktualna, na zdefiniowanie najpierw ścisłego kontraktu, w którym dokumentacja dla użytkownika i server boilerplate są generowane z dokładnie tego samego source of truth. To wszystko w tym odcinku. Dzięki za wysłuchanie i udanego kodowania!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 3 z 19. Zanim zaprojektujesz złożone API, potrzebujesz czystej karty, ale zaczynając od złej struktury bazowej, po cichu zepsujesz swój cały toolchain na późniejszym etapie. I to prowadzi nas do anatomii dokumentu OpenAPI. W swojej istocie, dokument OpenAPI definiuje się ściśle jako obiekt JSON. Możesz napisać swój plik w formacie JSON lub YAML. Tooling obsługuje oba formaty, a pod spodem model danych pozostaje dokładnie taki sam. Ponieważ mapuje się on bezpośrednio na standardowy obiekt JSON, reguły formatowania są sztywne. Każda nazwa pola jest w pełni case-sensitive. Jeśli specyfikacja wymaga nazwy pola pisanej małą literą, zapisanie jej z wielkiej litery na początku sprawi, że parser ją zignoruje albo rzuci błędem. Organizując swój projekt, masz wybór co do struktury dokumentu. Możesz zdefiniować wszystko w jednym, monolitycznym pliku. Alternatywnie, możesz podzielić swoje definicje na strukturę wielodokumentową. W setupie wielodokumentowym, plik root działa jako entry point i linkuje do zewnętrznych plików używając referencji. Niezależnie od tego, czy używasz jednego, czy pięćdziesięciu plików, parser ostatecznie sprowadza je do pojedynczego, logicznego obiektu JSON w pamięci. Weźmy konkretny scenariusz. Zaczynasz zupełnie nowy projekt. Tworzysz pusty plik tekstowy o nazwie openapi dot yaml. Zanim spróbujesz zaprojektować jakąkolwiek logikę, chcesz ustalić zwalidowany baseline. Aby przejść przez walidator schematu, twoja czysta karta musi zawierać dokładnie dwa pola na poziomie root. Pierwsze wymagane pole nazywa się openapi. Jego wartość to string, który określa dokładną wersję specyfikacji OpenAPI, której używasz, na przykład 3.1.0. Niezwykle często myli się to pole z wersją twojego własnego API. Są one ze sobą całkowicie niezwiązane. String z wersją openapi istnieje wyłącznie dla kompatybilności toolingu. Kiedy generator kodu albo przeglądarka dokumentacji otwiera twój plik, najpierw czyta to pole, aby ustalić, jakich reguł parsowania użyć. Jeśli zadeklarujesz tutaj 3.0.0, ale użyjesz feature'ów z 3.1.0, twoje narzędzia do walidacji zwrócą błąd, ponieważ będą ewaluować twój dokument względem złego zestawu reguł. Oto kluczowa sprawa. Drugie wymagane pole na poziomie root to miejsce, gdzie trafiają faktyczne szczegóły twojego API. Tym polem jest obiekt info. Obiekt info dostarcza metadane dla twojej aplikacji. Nie będziemy tu wchodzić w szczegóły jego wewnętrznej zawartości, powiemy tylko, że wymaga tytułu i swojego własnego stringa z wersją. Ten wewnętrzny string z wersją wewnątrz obiektu info to miejsce, w którym definiujesz, czy twoja aplikacja jest w wersji pierwszej, czy drugiej. Kiedy twój plik openapi dot yaml zawiera tylko te dwa pola root, openapi i info, masz strukturalnie kompletny dokument OpenAPI. Możesz teraz przepuścić ten plik przez walidator i przejdzie on bez problemu. Ustalenie tej minimalnej, poprawnej struktury gwarantuje, że twój parser i toolchain działają idealnie, zanim wprowadzisz złożoność faktycznej logiki routingu. Dzięki za wysłuchanie, miłego kodowania wszystkim!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 4 z 19. Jeśli twoje API przestanie działać, skąd konsument ma wiedzieć, z kim się skontaktować? Odpowiedź znajduje się na samym początku twojej specyfikacji. Mówimy o przygotowaniu gruntu, czyli obiektach Info i Servers. Zanim developer w ogóle wyśle request albo sprawdzi model danych, potrzebuje kontekstu. Obiekty Info i Server zapewniają dokładnie to. Pomyśl o nich jak o stronie tytułowej i książce adresowej twojego API. Obiekt Info to twoje centrum metadanych. Dwa pola są tutaj absolutnie wymagane. Pierwsze to title, czyli po prostu czytelna dla człowieka nazwa twojej aplikacji. Drugie to version. Ludzie często mylą to z wersją specyfikacji OpenAPI. To dwie zupełnie różne rzeczy. Wersja OpenAPI mówi parserowi, jakiego zestawu reguł składniowych ma przestrzegać. Z kolei version w obiekcie Info to numer wydania twojego API, na przykład 1.0.5. Mówi konsumentowi, na którą iterację produktu właśnie patrzy. Poza wymaganymi polami, obiekt Info pozwala ci dodać więcej kontekstu. Możesz dorzucić pole description, które obsługuje formatowanie CommonMark. Dzięki temu możesz pisać szczegółową, czytelną dokumentację z akapitami i linkami bezpośrednio w specyfikacji. Możesz też zdefiniować obiekt contact, zawierający name, URL i adres e-mail. Jeśli coś się zepsuje albo developer będzie potrzebował dostępu, to powie mu dokładnie, gdzie ma się zgłosić. Na koniec, obiekt license pozwala ci określić warunki prawne, na jakich działa API. Wymaga on podania pola name i opcjonalnie adresu URL wskazującego na tekst licencji. Kiedy obiekt Info ustali już, czym jest twoje API, tablica Servers mówi konsumentowi, gdzie ono żyje. Bez tego konsumenci wiedzą, co robi twoje API, ale nie wiedzą, gdzie je znaleźć. Podajesz tablicę obiektów Server, reprezentujących różne środowiska, w których hostowane jest twoje API. Każdy obiekt Server wymaga jednego pola, którym jest URL. I tu pojawia się kluczowa kwestia. Nie ograniczasz się do jednego base URL. Możesz zdefiniować wiele wpisów w tablicy Servers, aby odzwierciedlić swoją rzeczywistą infrastrukturę. Na przykład, twój pierwszy obiekt Server może zawierać produkcyjny URL z bezpiecznym adresem HTTPS, z polem description wyraźnie oznaczającym go jako środowisko produkcyjne live. Twój drugi obiekt Server może wskazywać na URL środowiska staging lub sandbox, z opisem informującym, że służy ono wyłącznie do testów. Kiedy ustrukturyzujesz swoje serwery w ten sposób, interaktywne narzędzia do dokumentacji i generatory klientów stają się znacznie potężniejsze. Zamiast zmuszać developera do ręcznego konfigurowania base URL dla każdego requestu, może on po prostu wybrać staging lub produkcję z rozwijanego menu w swoim interfejsie. Narzędzia parsują twoją tablicę Servers i automatycznie kierują requesty do odpowiedniego hosta. Możesz również użyć relatywnych adresów URL, jeśli twój dokument OpenAPI jest hostowany bezpośrednio na serwerze, który udostępnia to API. Ułatwia to zrobienie deployu dokładnie tego samego pliku specyfikacji na różnych środowiskach, bez ciągłego aktualizowania adresu hosta. Zdefiniowanie dokładnych obiektów Info i Server oznacza, że twoje API nie jest tylko luźnym zbiorem operacji, ale w pełni zidentyfikowaną, jasną pod względem prawnym i fizycznie lokalizowalną usługą. Jakość każdej zautomatyzowanej integracji będzie zależeć całkowicie od dokładności tych adresów base URL. To wszystko w tym odcinku. Dzięki za wysłuchanie i budujcie dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 5 z 19. Każde REST API potrzebuje endpointów, ale jak matematycznie udowodnić maszynie, gdzie które metody HTTP są dozwolone? Musisz je logicznie zmapować. Dzisiaj przyjrzymy się mapowaniu ścieżek i operacji w API. Pomyśl o Paths Object w OpenAPI jako o centralnym routerze twojej dokumentacji. Działa on jak katalog, który mapuje względne adresy URL na określone możliwości. Zanim przyjrzymy się temu, co znajduje się w środku, musimy wyjaśnić powszechne nieporozumienie. Ścieżki zawsze muszą zaczynać się od slasha. Są one ściśle względne w stosunku do twojego Server URL, nigdy bezwzględne. Jeśli twoje API jest hostowane pod adresem api kropka example kropka com, twoja ścieżka to po prostu slash users, a nie pełna domena. Specyfikacja opiera się na tym dokładnym formatowaniu, aby poprawnie dołączyć ścieżkę do bazowego adresu serwera. Wewnątrz Paths Object definiujesz poszczególne routy za pomocą kluczy typu string. Wartość przypisana do każdego klucza routingu nazywa się Path Item Object. Path Item Object to w zasadzie po prostu kontener. Grupuje on wszystkie metody HTTP dozwolone dla tego konkretnego adresu URL. Nie narzuca on bezpośrednio inputów ani outputów. Zamiast tego przechowuje klucze reprezentujące standardowe metody HTTP, takie jak get, post, put lub delete. Kiedy mapujesz jedną z tych metod HTTP wewnątrz Path Item, wartość, którą do niej przypisujesz, to Operation Object. To właśnie w Operation Object definiujesz faktyczną akcję. Opisuje on dokładnie, co klient może zrobić, wysyłając tę konkretną metodę na tę konkretną ścieżkę. Aby zwizualizować sobie tę strukturę, weźmy pod uwagę standardowy endpoint do zarządzania użytkownikami. W swoim głównym Paths Object definiujesz klucz o nazwie slash users. Wartość do niego przypisana to twój Path Item Object. Wewnątrz tego kontenera definiujesz klucz get i klucz post. Klucz get zawiera Operation Object, który wyjaśnia, w jaki sposób API zwraca listę użytkowników. Klucz post zawiera zupełnie oddzielny Operation Object, który opisuje, jak utworzyć nowego użytkownika. Obie operacje współdzielą identyczny URL slash users, ale specyfikacja traktuje je jako odrębne logiczne akcje zagnieżdżone pod ich odpowiednimi kluczami metod HTTP. Wewnątrz każdego Operation Object zazwyczaj definiujesz dwa pola w celu ustalenia tożsamości: summary i operationId. Summary to krótki string przeznaczony dla ludzi. W przypadku metody get na naszej ścieżce slash users, summary może po prostu brzmieć "List all registered users". Pojawia się ono w wygenerowanych interfejsach dokumentacji, dzięki czemu developerzy mogą szybko przeskanować dostępne endpointy. Oto kluczowa kwestia. Pole operationId jest przeznaczone dla maszyn. Jest to unikalny string używany do identyfikacji operacji w całym dokumencie API. Generatory kodu w dużym stopniu polegają na operationId, aby nazywać funkcje i metody wewnątrz klienckich SDK, które budują. Jeśli nadasz swojej operacji get operationId o wartości listUsers, wygenerowany klient w Pythonie lub TypeScripcie będzie zawierał funkcję o nazwie listUsers. Ten string musi być absolutnie unikalny. Jeśli dwie operacje współdzielą ten sam operationId, zautomatyzowane narzędzia do generowania wyprodukują zepsuty kod lub całkowicie się wysypią. Struktura opiera się na ścisłym, przewidywalnym zagnieżdżaniu. Paths mapują się na Path Items, Path Items mapują się na metody HTTP, a metody mapują się na Operation Objects zdefiniowane przez unikalne identyfikatory. Opanowanie tej dokładnej hierarchii gwarantuje, że zarówno developerzy, jak i narzędzia do automatyzacji będą mogli wchodzić w interakcję z architekturą twojego API bez zgadywania. To wszystko w tym odcinku. Do usłyszenia następnym razem!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 6 z 19. Statyczne endpointy nie wystarczą na długo. Żeby zbudować naprawdę użyteczne API, potrzebujesz sposobu na przekazywanie dynamicznych argumentów bezpośrednio przez request, aby zmienić sposób wykonania operacji lub dane, na których ona operuje. Ten odcinek w całości poświęcony jest dynamicznym endpointom z parametrami. Zacznijmy od samej ścieżki URL. W OpenAPI definiujesz dynamiczne sekcje adresu URL za pomocą path templating. Robisz to, umieszczając nazwę zmiennej w nawiasach klamrowych. Wyobraź sobie API e-commerce. Jeśli chcesz pobrać konkretne zamówienie, twoja ścieżka wygląda tak: slash orders slash lewy nawias klamrowy orderId prawy nawias klamrowy. W swoim dokumencie OpenAPI opisujesz tę zmienną za pomocą Parameter Object. Określasz jej lokalizację, ustawiając pole in na wartość path. Ludzie czasami próbują sprawić, by parametry ścieżki były opcjonalne. Nie możesz tego zrobić. Parametr ścieżki strukturalnie definiuje route. Jeśli brakuje parametru, ten route po prostu nie istnieje. Z powodu tej reguły, każdy parametr, którego lokalizacją jest path, musi zawsze mieć pole required ustawione na true. A co, jeśli potrzebujesz opcjonalnych modyfikatorów? To prowadzi nas do drugiej lokalizacji, gdzie pole in równa się query. Query parameters pojawiają się na samym końcu adresu URL, po znaku zapytania. Wracając do naszego API e-commerce, możesz chcieć pobrać listę zamówień, ale chcesz zobaczyć tylko te, które są już w drodze. Do adresu URL doklejasz znak zapytania status równa się shipped. W przeciwieństwie do parametrów ścieżki, query parameters nie definiują lokalizacji zasobu. Filtrują lub modyfikują wynik, co oznacza, że ich pole required może być ustawione na true albo false. Adres URL to nie jedyne miejsce do przekazywania parametrów. Parameter Object obsługuje dwie dodatkowe lokalizacje. Ustawienie pola in na header pozwala ci zdefiniować customowe nagłówki HTTP oczekiwane przez twoją operację. Na przykład, możesz wymagać customowego nagłówka wskazującego na konkretny typ urządzenia klienta. Zauważ, że standardowe nagłówki, takie jak Accept czy Authorization, są całkowicie wykluczone z Parameter Object, ponieważ są obsługiwane w innym miejscu w OpenAPI. I wreszcie, ustawienie lokalizacji na cookie pozwala ci dokumentować parametry przekazywane przez cookies przeglądarki, takie jak tymczasowy token sesji. Zadeklarowanie, gdzie żyje parametr, to dopiero pierwszy krok. Musisz również zdefiniować jego kształt. Wewnątrz Parameter Object używasz pola schema, aby zdefiniować bazowy typ danych. To mówi konsumentowi API dokładnie, czy ten orderId to integer, string, czy specyficzny format, taki jak UUID. Następnie masz pole style. Dyktuje ono, jak parametr jest serializowany do requestu HTTP. Serializacja ma ogromne znaczenie, gdy przekazujesz złożone dane, takie jak tablice czy obiekty. Jeśli przekazujesz listę statusów w query stringu, pole style określa format. Wartość style ustawiona na form może oddzielać wiele wartości ampersandem, podczas gdy wartość style równa simple wyrzuca listę oddzieloną przecinkami. Łącząc pola lokalizacji, schema i style, dajesz klientowi dokładne instrukcje, jak sformatować request sieciowy. Oto kluczowa rzecz. Parameter Object nie opisuje inputów tylko z grzeczności. Ściśle dyktuje dokładny kształt tego, co akceptuje operacja, wymuszając typy danych i formaty, zanim wykona się choćby jedna linijka logiki twojego backendu. Jeśli uważasz te odcinki za pomocne, możesz wesprzeć program, wyszukując DevStoriesEU na Patreonie. To wszystko w tym odcinku. Dzięki za wysłuchanie i buduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 7 z 19. Kiedy wysyłasz setki pól do API, query parameters przestają się sprawdzać. Potrzebujesz ustrukturyzowanej paczki. Ta paczka jest definiowana przez Structuring Input Request Bodies. Podczas gdy requesty GET opierają się na ścieżce URL i query stringu, requesty POST, PUT i PATCH odwalają czarną robotę, przenosząc payload. Ten payload zawiera złożone, zagnieżdżone dane. W starszych specyfikacjach Swagger 2.0 możesz pamiętać definiowanie body parameters lub form parameters bezpośrednio obok inputów typu header i path. OpenAPI w wersji trzeciej całkowicie to zmieniło. Całkowicie porzucono body parameters i wprowadzono pojedynczy, dedykowany Request Body Object. Request Body Object znajduje się na poziomie operacji w twoim projekcie API. Jego cechą charakterystyczną jest to, że w dużej mierze opiera się na content negotiation. Nie tylko opisujesz dane, ale mapujesz je na konkretne media types. To mapowanie odbywa się wewnątrz content map. Content map to słownik, w którym klucze to standardowe MIME types, takie jak application slash json, a wartości to Media Type Objects, szczegółowo opisujące, jak wygląda ten konkretny payload. Wyobraź sobie, że klient uploaduje nowy profil użytkownika. Profil zawiera imię, adres e-mail, preferencje użytkownika i zagnieżdżony obiekt adresu. Zamiast upychać to w URL variables, klient wysyła JSON payload. W twoim dokumencie OpenAPI, w sekcji request body, tworzysz content map z dokładnym kluczem application slash json. To wyraźnie deklaruje, że API akceptuje tylko JSON dla tej operacji. Jeśli klient spróbuje wysłać XML lub plain text, serwer od razu wie, żeby odrzucić request z błędem unsupported media type. Ta struktura jest bardzo elastyczna. Jeśli upload profilu użytkownika wymaga zdjęcia profilowego obok danych tekstowych, obsługujesz to dokładnie w tym samym miejscu. Dodajesz drugi klucz do content map dla multipart slash form-data. Ten Media Type Object określa wtedy reguły dla mieszanego payloadu. Każdy media type dostaje swoją własną, niezależną definicję. Pozwala to dokładnie temu samemu endpointowi API przetwarzać całkowicie różne formaty danych, opierając się wyłącznie na headerze Content-Type, który klient wysyła w requeście HTTP. W samym Request Body Object, obok content map, znajdziesz flagę required. To prosta właściwość typu boolean. Ustawienie jej na true oznacza, że request natychmiast zakończy się błędem, jeśli klient wyśle puste body. Wymusza to obecność payloadu, zanim serwer w ogóle spróbuje zwalidować dane w środku. Same reguły strukturalne payloadu są obsługiwane przez schemę podpiętą do Media Type Object, chociaż głęboka mechanika projektowania JSON Schema zostanie omówiona w dziesiątym odcinku. Oto kluczowy wniosek. Request Body Object oddziela surowy payload z danymi od parametrów transportu HTTP, pozwalając pojedynczemu endpointowi wymuszać zupełnie inne reguły walidacji w oparciu wyłącznie o media type zadeklarowany w content map. To wszystko w tym odcinku. Dzięki za wysłuchanie i twórzcie dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 8 z 19. Większość developerów dokumentuje happy path, ale prawdziwa odporność API bierze się ze ścisłego zdefiniowania, jak dokładnie coś może pójść nie tak. Jeśli informujesz klientów tylko o tym, co się dzieje, gdy wszystko idzie idealnie, twoje API jest udokumentowane tylko w połowie. Dzisiaj przyjrzymy się oczekiwaniom i Error Responses. W OpenAPI, responses stanowią ostateczną gwarancję kontraktu. Formalizują obietnicę, że jeśli klient wyśle konkretny request, API zwróci znany payload albo ustrukturyzowany błąd. Ta obietnica jest obsługiwana przez Responses Object. Pomyśl o tym jak o tabeli routingu dla wyników. Klucze w tej mapie to kody statusu HTTP zapisane jako stringi, takie jak tekst 200 lub 404. Wartości przypisane do tych kluczy to pojedyncze Response Objects, które szczegółowo opisują, co dokładnie wraca do klienta przez sieć. Oto kluczowa uwaga na temat formatowania tych obiektów. W dużej części OpenAPI, pola description są całkowicie opcjonalne. Używasz ich, gdy chcesz dodać przydatny kontekst dla innych developerów. W Response Object, pole description jest absolutnie wymagane. Jeśli je pominiesz, cała twoja definicja API stanie się nieprawidłowa. Nie musi to być długi akapit. Wystarczy krótka, trafna fraza wyjaśniająca wynik, ale parser wymusi jej obecność. Weźmy pod uwagę praktyczny scenariusz, w którym klient wysyła request o konkretny profil użytkownika. Dla pomyślnego wyniku, definiujesz klucz dla stringa 200. Wewnątrz tego Response Object podajesz obowiązkowe description, na przykład Pomyślne pobranie użytkownika. Następnie definiujesz pole content. To pole mapuje media type, najczęściej application/json, bezpośrednio na schema, które definiuje strukturę twojego obiektu użytkownika. Kod klienta wie teraz dokładnie, jakich właściwości oczekiwać, gdy wywołanie się powiedzie. To pokrywa oczekiwany wynik. Teraz musisz udokumentować błąd. W tym samym Responses Object definiujesz kolejny klucz dla 404. Wymagane description może po prostu brzmieć Nie znaleziono użytkownika. Podobnie jak w przypadku sukcesu, pole content mapuje tutaj application/json na schema, ale tym razem wskazuje na twoją ustandaryzowaną strukturę błędu. Dzięki temu jawnemu kontraktowi, aplikacja kliencka może bezpiecznie sparsować error response i wyświetlić użytkownikowi końcowemu pomocny prompt, zamiast crashować na nieoczekiwanych danych. Zawsze będą przypadki, w których nie przewidzisz każdego pojedynczego kodu błędu, jaki może wygenerować twoja architektura. Reverse proxy może rzucić 502 Bad Gateway, a web application firewall może wstrzyknąć 403 Forbidden. Tutaj do gry wchodzi wildcard default. Zamiast numerycznego kodu statusu HTTP, jako klucza używasz dokładnego słowa default. Działa to jako definicja catch-all. Jeśli serwer zwróci jakikolwiek kod statusu, którego nie wylistowałeś jawnie w Responses Object, klient robi fallback do struktury zdefiniowanej pod default. Działa to jak siatka bezpieczeństwa dla generycznego error handlingu, upewniając się, że klient nadal wie, jak odczytać error payload. Naprawdę solidna definicja API nie tylko wyjaśnia idealny scenariusz; zapewnia precyzyjną, przewidywalną mapę dla każdego możliwego sposobu, w jaki system może zawieść. Dzięki za spędzenie ze mną tych kilku minut. Do usłyszenia następnym razem, trzymaj się.

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 9 z 19. Jeśli twoje API ma 100 endpointów i wszystkie zwracają dokładnie tę samą strukturę paginacji, copy-pasting to przepis na katastrofę. Jedna niewielka zmiana w nazwie pola oznacza ręczne szukanie 100 definicji rozrzuconych po całym dokumencie. Mechanizmem strukturalnym, który rozwiązuje ten problem, jest reużywalność przy użyciu Components. Specyfikacja OpenAPI rozwiązuje problem puchnięcia specyfikacji poprzez dedykowaną sekcję na poziomie root o nazwie Components Object. Pomyśl o tym jak o scentralizowanym słowniku lub wewnętrznej bibliotece dla twojej definicji API. Zamiast definiować złożone struktury danych, standardowe query parameters czy powtarzające się odpowiedzi serwera inline pod każdą pojedynczą ścieżką path, deklarujesz je dokładnie raz wewnątrz Components Object. To ustanawia ścisłe single source of truth. Zanim przejdę do mechaniki, muszę rozwiać pewne powszechne nieporozumienie na temat tego, jak zachowuje się ta sekcja. Zdefiniowanie schema, nagłówka lub parametru wewnątrz Components Object nie powoduje automatycznego wystawienia go w twojej dokumentacji API ani w logice routingu. Sekcja components jest całkowicie pasywna. Nie ma żadnego bezpośredniego wpływu na twoje endpointy. Komponent ma znaczenie tylko wtedy, gdy konkretny path lub operacja jawnie na niego wskazuje. Aby powołać komponent do aktywnej służby, używasz Reference Object. W składni OpenAPI jest to reprezentowane przez słowo kluczowe dollar-sign-ref. Reference Object używa JSON Pointer, aby powiedzieć narzędziom, gdzie dokładnie zlokalizować współdzieloną definicję. Standardowy wewnętrzny string pointera zaczyna się od symbolu hash, po którym następuje slash, słowo components, kolejny slash, nazwa konkretnej kategorii, a na końcu customowa nazwa, którą nadałeś swojemu obiektowi. Oprzyjmy to na konkretnym scenariuszu. Prawie każde API wymaga spójnego sposobu zwracania błędów po stronie klienta i serwera. Chcesz, aby twoje odpowiedzi 400 Bad Request i 500 Internal Server Error dzieliły dokładnie tę samą strukturę we wszystkich endpointach, zawierając na przykład kod błędu typu integer i opisowy string z wiadomością. Najpierw schodzisz do swojego root Components Object. Wewnątrz niego otwierasz kategorię o nazwie schemas. Pod schemas definiujesz nowy generyczny obiekt o nazwie ErrorModel i określasz swoje properties dla code i message. Twoja generyczna struktura błędu jest teraz bezpiecznie przechowana. Następnie przechodzisz wyżej, do swoich paths w API. Kiedy definiujesz odpowiedź z poziomu 400 dla endpointu tworzenia użytkownika, całkowicie pomijasz wypisywanie properties dla schema inline. Zamiast tego podajesz klucz dollar-sign-ref. Jego wartością jest dokładna ścieżka do twojego zapisanego schema: hash-slash-components-slash-schemas-slash-ErrorModel. Wstawiasz dokładnie ten sam string referencyjny do odpowiedzi z poziomu 500. Powtarzasz tę referencję w swoich endpointach do płatności, endpointach do autentykacji i endpointach do wyszukiwania. Dziesiątki operacji wskazują teraz na jedną definicję. Ta strategia organizacyjna wykracza daleko poza schemas. Components Object udostępnia konkretne kategorie dla różnych elementów API. Możesz przechowywać standardowe argumenty paginacji wewnątrz kategorii parameters. Możesz definiować całe struktury payloadu w requestBodies, albo standardowe wymagania autoryzacyjne w securitySchemes. Logika operacyjna pozostaje identyczna dla nich wszystkich. Zdefiniuj obiekt raz w odpowiadającym mu koszyku, a następnie wepnij go w swoje operacyjne paths za pomocą referencji. Oto kluczowy wniosek. Budowanie łatwej w utrzymaniu specyfikacji API to w gruncie rzeczy kontrolowanie duplikacji. Kiedy pojawia się nowe wymaganie, które zmusza cię do dodania pola timestamp do każdej odpowiedzi z błędem, użycie components oznacza, że edytujesz ErrorModel w dokładnie jednym miejscu, a każda operacja w całym twoim API automatycznie dziedziczy tę aktualizację. To wszystko na dzisiaj. Do usłyszenia następnym razem!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 10 z 19. Wiesz, czym jest integer, ale twoja baza danych musi wiedzieć, czy to wartość 32-bitowa, czy 64-bitowa. Schematy wypełniają tę lukę. Ten odcinek poświęcony jest wyłącznie typom danych i schematom. Obiekt Schema działa jak rygorystyczny silnik walidacji dla twojego API. Znajduje się bezpośrednio pod twoimi parametrami, ciałami requestów i odpowiedziami. Zamiast po prostu mówić klientowi, żeby wysłał generyczny JSON payload, schemat dyktuje dokładny kształt, typ i granice tych danych. Działa jak ścisły filtr na granicy twojego systemu. Jeśli przychodzący request nie pasuje do reguł zdefiniowanych w schemacie, nie przechodzi walidacji, zanim logika twojej aplikacji w ogóle go zobaczy. Historycznie, deweloperzy napotykali na spory problem przy definiowaniu tych reguł. OpenAPI w wersji 3.0 używało własnego, zmodyfikowanego dialektu JSON Schema. Był bliski standardowi, ale fundamentalnie niekompatybilny w kilku frustrujących kwestiach, co powodowało niekończące się problemy z toolingiem. OpenAPI w wersji 3.1 całkowicie to rozwiązuje. To nie jest już customowy dialekt. OpenAPI 3.1 jest teraz w pełni zgodne z nowoczesnym JSON Schema. Mówiąc dokładniej, działa jako superset dla JSON Schema Draft 2020-12. Oznacza to, że każdy standardowy dokument JSON Schema, który już masz, jest automatycznie prawidłowym schematem OpenAPI 3.1. Bycie supersetem oznacza po prostu, że OpenAPI dodaje od siebie kilka słów kluczowych specyficznych dla API, takich jak identyfikatory konfiguracji XML, bez psucia bazowego standardu. W samym sercu tych reguł schematu leży słowo kluczowe type. OpenAPI opiera się na prymitywnych typach danych zdefiniowanych przez JSON Schema. Masz do dyspozycji typy string, integer, number i boolean. Rozróżnienie między typem number a integer jest ściśle egzekwowane. Typ number obsługuje wartości zmiennoprzecinkowe i double, podczas gdy typ integer kategorycznie odrzuca wszystko, co ma ułamek dziesiętny. Oto kluczowa sprawa. Wiedza o tym, że coś jest po prostu stringiem lub integerem, rzadko daje wystarczający kontekst dla systemu backendowego. I tutaj modyfikator format staje się niezbędny. Słowo kluczowe format zawęża ogólny typ prymitywny do czegoś konkretnego, pod co twój kod może zaalokować pamięć lub z czym może się zwalidować. Typ prymitywny mówi parserowi JSON, jak odczytać surowe dane, a format mówi twojej aplikacji, jak dokładnie zinterpretować tę wartość. Na przykład, jeśli zdefiniujesz właściwość jako integer, możesz dodać format int32 lub int64, aby określić jej dokładny rozmiar w bajtach. Jeśli twój typ to string, możesz zastosować format taki jak date-time, password lub email. Specyfikacja OpenAPI definiuje standardowy rejestr tych formatów, ale to pole jest ostatecznie otwartym stringiem, co oznacza, że tooling może obsługiwać customowe formaty, jeśli twoja aplikacja ich wymaga. Przejdźmy przez konkretny scenariusz. Musisz zdefiniować obiekt User dla endpointu rejestracji. Zaczynasz od utworzenia schematu o typie object. Wewnątrz tego obiektu definiujesz dwie właściwości: ID oraz adres email. Dla właściwości ID ustawiasz typ na integer, a format na int64. Dla właściwości adresu email ustawiasz typ na string, a format na email. Na koniec określasz tablicę wymaganych właściwości, zawierającą nazwy obu pól: ID oraz email. Masz teraz ścisły, wykonywalny kontrakt. Jeśli klient wyśle właściwość email, która nie przypomina prawidłowego adresu email, albo ID, które przekracza 64-bitowy limit liczbowy, API gateway lub framework natychmiast odrzuci ten payload. Precyzja na granicy API oszczędza ci pisania niekończącej się logiki sprawdzania danych w twoich kontrolerach. To wszystko w tym odcinku. Dzięki za wysłuchanie i koduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. Ekosystem OpenAPI i Swaggera, odcinek 11 z 19. Zanim będziesz mógł chronić wrażliwy endpoint, musisz formalnie zadeklarować, jak dokładnie wygląda prawidłowy identyfikator. Nie możesz po prostu żądać uwierzytelnienia od klienta. Musisz określić dokładny mechanizm, którego ma użyć, adresy URL, które ma odpytywać, oraz parametry, które musi wysłać. Definiowanie security schemes to sposób na rozwiązanie tego problemu. Potraktuj ten krok jako inwentaryzację zamków istniejących w twoim systemie. Opisujesz dostępne typy zamków, ale nie instalujesz ich jeszcze na żadnych konkretnych drzwiach. W OpenAPI definiujesz te zamki wewnątrz obiektu components, a konkretnie w sekcji o nazwie security schemes. Każdy zamek otrzymuje wybraną przez ciebie nazwę referencyjną. Pod tą nazwą deklarujesz jego typ i wymagane properties. W specyfikacji OpenAPI trzy kropka jeden istnieje pięć głównych typów security schemes. Pierwszym z nich jest typ http. Obejmuje to standardowe mechanizmy uwierzytelniania HTTP zdefiniowane w dokumencie RFC 7235, takie jak uwierzytelnianie Basic lub Bearer. Aby zdefiniować standardowy schemat tokena HTTP Bearer, tworzysz wpis w sekcji security schemes. Ustawiasz property type na string http, a property scheme na string bearer. Możesz też opcjonalnie dodać property bearer format, aby zasugerować typ tokena, na przykład podając string JWT. Oto kluczowa sprawa. Kiedy używasz schematu http bearer, specyfikacja niejawnie zakłada, że token zostanie wysłany w standardowym nagłówku HTTP Authorization. Nie mówisz OpenAPI, gdzie ma szukać. Ale drugi typ, schemat api key, jest zupełnie inny. W przypadku api key musisz jawnie określić zarówno property name, czyli dokładną nazwę pola, jak i property in, które dyktuje, gdzie ten klucz trafia. Property in akceptuje tylko trzy wartości: query, header lub cookie. Jeśli oczekujesz niestandardowego nagłówka, takiego jak X API Key, użyj typu api key. Jeśli używasz standardowych nagłówków Authorization, użyj typu http. Trzecim typem jest oauth2. Wymaga on bardziej złożonej konfiguracji strukturalnej, ponieważ OAuth2 ma wiele odrębnych flows. Aby zdefiniować złożony authorization code flow w OAuth2, zaczynasz od ustawienia type na oauth2. Następnie podajesz obiekt flows. Wewnątrz flows dodajesz obiekt authorization code. Ten zagnieżdżony obiekt wymaga dwóch konkretnych adresów URL. Podajesz authorization url, pod którym loguje się użytkownik, oraz token url, pod którym aplikacja wymienia kod na token. Musisz również podać obiekt scopes, który mapuje konkretne nazwy scope'ów na krótkie opisy tekstowe tego, na co te scope'y pozwalają. Czwartym typem jest open id connect. Jest on znacznie prostszy do zadeklarowania niż OAuth2. Ustawiasz type na open id connect i podajesz pojedyncze property open id connect url. Wskazuje to bezpośrednio na tak zwany discovery document, którego klienci używają do automatycznej konfiguracji. Wreszcie, piątym typem jest mutual t l s, co oznacza mutual Transport Layer Security. Po prostu ustawiasz type na mutual t l s. Sygnalizuje to, że klient musi dostarczyć certyfikat X 509 podczas początkowego TLS handshake w celu uwierzytelnienia, całkowicie poza warstwą aplikacji HTTP. Najważniejszym wnioskiem jest to, że definiowanie security schemes oddziela mechanizm uwierzytelniania od endpointów, które go wymagają. Budujesz swoje zamki raz w scentralizowanym katalogu, upewniając się, że klienci wiedzą dokładnie, jak sformatować swoje credentials, zanim w ogóle spróbują zapukać. Przy okazji, jeśli chcesz wesprzeć podcast, możesz wyszukać DevStoriesEU na Patreonie. To wszystko w tym odcinku. Dzięki za słuchanie i buduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 12 z 19. Wdrażanie security to sztuka balansu: chcesz globalnie zamknąć cały sejf, ale zostawić lobby otwarte dla gości. Aby to zrobić i samemu się nie zablokować, musisz zrozumieć, jak OpenAPI aplikuje Security Requirements. Kiedy już zdefiniujesz swoje security schemes w sekcji components swojego dokumentu OpenAPI, musisz je faktycznie podpiąć pod swoje endpointy. Robisz to za pomocą tablicy security. Ta tablica zawiera Security Requirement Objects, które odwołują się do nazw schemes, które zbudowałeś wcześniej. Możesz zadeklarować tę tablicę security w dwóch miejscach: globalnie w roocie twojego dokumentu OpenAPI, albo lokalnie wewnątrz konkretnego Operation Object. Jeśli zdefiniujesz ją w roocie, każdy pojedynczy endpoint w twoim API dziedziczy to wymaganie. Jeśli zdefiniujesz ją wewnątrz operacji, całkowicie nadpisuje ona globalną konfigurację. Nie merguje się z globalnymi ustawieniami, tylko całkowicie je zastępuje. Wyobraź sobie scenariusz, w którym ustawiasz globalne wymaganie, że każdy route w API potrzebuje tokena Bearer. To zabezpiecza sejf. Ale masz też route do logowania. Jeśli route logowania odziedziczy to globalne wymaganie tokena, nowi użytkownicy nigdy się nie uwierzytelnią, bo nie mają jeszcze tokena. Musisz nadpisać tę globalną blokadę. Częstym błędem jest po prostu pominięcie pola security w operacji logowania, przy założeniu, że oznacza to brak security. Jeśli pominiesz to pole, operacja po prostu przyjmie domyślne globalne wymaganie, a twoi użytkownicy zostaną zablokowani. Aby jawnie pozwolić na anonimowy dostęp, musisz zdefiniować tablicę security w operacji logowania i wrzucić do niej pusty obiekt. Ten pusty obiekt mówi OpenAPI, że wymagania dostępu do tego konkretnego endpointu po prostu nie ma. Globalna blokada zostaje ominięta, a goście mogą wejść do lobby. Tutaj zaczyna się robić ciekawie. Sposób, w jaki układasz elementy w tablicy security, dyktuje logikę twojej autentykacji. Obsługuje to scenariusze logicznego OR oraz logicznego AND, bazując wyłącznie na granicach obiektów. Jeśli twoja tablica zawiera dwa oddzielne Security Requirement Objects, na przykład jeden obiekt wymagający API key, a drugi, oddzielny obiekt wymagający OAuth2, tworzy to logiczne OR. API zaakceptuje request, jeśli klient spełni warunki pierwszego albo drugiego obiektu. Jeśli potrzebujesz logicznego AND, zmieniasz granice. Powiedzmy, że request musi mieć zarówno token OAuth2, jak i customowy podpis w headerze. Wrzucasz obie te nazwy schemes do pojedynczego Security Requirement Object. Ponieważ współdzielą ten sam obiekt, API wymaga, aby wszystkie były prawidłowe, zanim przepuści request. Kiedy piszesz te obiekty, mapujesz nazwę swojego scheme na tablicę. Jeśli używasz OAuth2 albo OpenID Connect, ta tablica wylistowuje konkretne scopes wymagane dla operacji, takie jak odczyt czy zapis danych. Jeśli używasz API key albo basic HTTP scheme, scopes nie mają zastosowania, więc musisz zmapować nazwę scheme na pustą tablicę, żeby spełnić wymagania specyfikacji. Fizyczna struktura twojej tablicy security to twoje główne narzędzie do definiowania logiki dostępu. Opanuj różnicę granic między listowaniem elementów w tablicy, a listowaniem ich wewnątrz pojedynczego obiektu, a będziesz w stanie zbudować dowolny flow autentykacji, jakiego potrzebuje twój system. To wszystko w tym odcinku. Dzięki za wysłuchanie i buduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 13 z 19. REST świetnie nadaje się do zadawania pytań, ale co się stanie, gdy to twoje API musi rozpocząć rozmowę? Asynchroniczne API z webhookami radzą sobie z tym, wypychając dane w momencie wystąpienia zdarzenia, całkowicie eliminując potrzebę ciągłego pollingu. W przeszłości konsumenci musieli pisać skrypty, które wielokrotnie sprawdzały twoje endpointy, aby zobaczyć, czy status się zmienił. Było to nieefektywne zarówno dla ich serwerów, jak i dla twoich. OpenAPI 3.1 rozwiązało to ograniczenie, wprowadzając pole webhooks na samym poziomie root dokumentu OpenAPI. Ten dodatek wprowadził pierwszorzędne wsparcie dla asynchronicznej komunikacji event-driven do standardowych specyfikacji API. Zamiast tylko dokumentować to, co klient wysyła do twojego serwera, pole webhooks pozwala ci udokumentować dokładnie odwrotną sytuację. Definiujesz requesty HTTP, które twoja platforma będzie inicjować i wysyłać do serwera konsumenta. Trzeba wyraźnie rozgraniczyć webhooki i callbacki, ponieważ specyfikacja OpenAPI obsługuje je zupełnie inaczej. Różnica polega na sposobie rejestrowania docelowego adresu URL. Callbacki są wyzwalane przez konkretny, aktywny request API. Klient uderza w endpoint subskrypcji w twoim API i podaje docelowy adres URL bezpośrednio w payloadzie requestu. Ponieważ są one powiązane z operacją, callbacki są definiowane wewnątrz tego konkretnego obiektu operacji. Webhooki są rejestrowane out-of-band. Deweloper loguje się do dashboardu zarządzania, przechodzi na stronę ustawień i wkleja swój docelowy adres URL do formularza. Specyfikacji API nie obchodzi, w jaki sposób uzyskano ten adres URL. Ponieważ webhooki istnieją niezależnie od jakiegokolwiek konkretnego wywołania API w runtime, są umieszczane na najwyższym poziomie twojego dokumentu OpenAPI, tuż obok standardowych ścieżek i komponentów. Aby udokumentować webhooka, otwierasz mapę webhooks na poziomie root. Każdy klucz w tej mapie to prosty string, który nazywa zdarzenie. Na przykład możesz użyć stringa payment dot successful. Wartość przypisana do tego klucza to standardowy Path Item Object. Jest to dokładnie ta sama struktura, której używasz do definiowania swoich normalnych endpointów REST. Wewnątrz tego Path Item Object deklarujesz metodę HTTP, której twoja platforma użyje do dostarczenia zdarzenia, co prawie zawsze jest requestem POST. Oto kluczowa kwestia. Perspektywa jest całkowicie odwrócona, ale narzędzia pozostają identyczne. Używasz standardowych obiektów schema do zdefiniowania body requestu, które wyśle twoja platforma. W scenariuszu payment dot successful określasz, że payload będzie obiektem JSON zawierającym unikalny identyfikator płatności, dokładną pobraną kwotę i timestamp. Możesz również zdefiniować nagłówki, co jest kluczowe dla webhooków, ponieważ zazwyczaj musisz udokumentować nagłówek podpisu kryptograficznego, aby konsument mógł zweryfikować, czy payload faktycznie pochodzi od ciebie. Na koniec dokumentujesz odpowiedzi, których oczekujesz od konsumenta. Możesz określić, że twój system oczekuje kodu statusu 200 OK w ciągu trzech sekund, w przeciwnym razie twój system ponowi próbę dostarczenia później. Standardyzując tę odwrotną dokumentację API, dajesz konsumentom wszystko, czego potrzebują do wygenerowania własnego kodu serwera. Wiedzą dokładnie, jaki payload parsować, jakie nagłówki walidować i jakie kody statusu zwracać. Pole webhooks na poziomie root przenosi projektowanie API z prostych interakcji request-response na w pełni udokumentowaną architekturę event-driven. To wszystko w tym odcinku. Dzięki za wysłuchanie i buduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 14 z 19. Utworzenie użytkownika to krok pierwszy, ale skąd zautomatyzowany klient intuicyjnie wie, gdzie pójść dalej, żeby pobrać ten profil użytkownika? Możesz zahardkodować workflow w kodzie klienta, ale to się posypie w momencie, gdy zmieni się struktura twojego API. Rozwiązaniem tego problemu są State Transitions z użyciem linków. W OpenAPI obiekt Link znajduje się wewnątrz response'a i mapuje dane z tej odpowiedzi na parametry innej operacji. Żeby było jasne, linki nie wykonują requestów automatycznie. Nie zamieniają OpenAPI w aktywny silnik do orkiestracji. Dostarczają po prostu statyczne instrukcje dla twojego toolingu, SDK czy dokumentacji, jak skonstruować kolejny logiczny request w danym workflow. Jeśli budowałeś już wcześniej API, możesz pomyśleć, że brzmi to dokładnie jak ścisły HATEOAS, gdzie serwer wysyła dynamiczne linki hipermedialne w payloadzie response'a. Linki w OpenAPI oferują przyjazną dla developerów alternatywę dla tego podejścia. Zamiast zmuszać backend do wstrzykiwania dynamicznych URI do każdego response'a w runtime'ie, linki OpenAPI opisują te przejścia stanu w workflow statycznie, w samej definicji API. Narzędzia klienckie mogą zrozumieć ten workflow bez konieczności parsowania live payloadów, żeby odkryć, jakie akcje są możliwe. Logika opiera się na połączeniu źródłowego response'a z docelową operacją. Weźmy pod uwagę standardowy request POST używany do utworzenia nowego użytkownika. Response zwraca body w formacie JSON, zawierające nowo wygenerowane ID użytkownika. Wewnątrz definicji tego konkretnego response'a dodajesz mapę links. Każdy wpis w tej mapie definiuje relację z inną operacją, na przykład z requestem GET, który pobiera profil użytkownika. Docelową operację identyfikujesz za pomocą jednego z dwóch wzajemnie wykluczających się pól. Pierwsze to operation ID, czyli prosty string pasujący do unikalnego identyfikatora docelowej operacji. Drugie to operation reference, które używa standardowego JSON Pointera do nawigacji po dokumencie OpenAPI i zlokalizowania docelowej ścieżki oraz metody HTTP. Operation ID jest zazwyczaj czystszym rozwiązaniem, jeśli twoje API definiuje je spójnie, podczas gdy operation reference przydaje się do wskazywania operacji w zewnętrznych dokumentach OpenAPI. Kiedy już wskażesz docelową operację, musisz przekazać jej odpowiednie dane. Robisz to za pomocą mapy parameters. Klucze w tej mapie reprezentują nazwy parametrów, których oczekuje docelowa operacja, na przykład path parameter z ID użytkownika. Wartości to runtime expressions, które mówią toolingowi, skąd wyciągnąć te dane z bieżącego kontekstu. Runtime expression to specyficzna składnia, która ewaluuje dane podczas wywołania API. Możesz napisać wyrażenie, które instruuje klienta, żeby zajrzał do response body, zlokalizował pole ID i wyciągnął jego wartość. Nie jesteś ograniczony tylko do response body. Runtime expressions mogą wyciągać wartości z response headers, oryginalnej ścieżki requestu lub oryginalnych query parameters tego requestu. Jeśli docelowa operacja wymaga request body zamiast samych parametrów, obiekt Link udostępnia pole request body. Pozwala ci to zmapować runtime expression bezpośrednio do payloadu kolejnego requestu. Kiedy generator SDK przetwarza te linki, może automatycznie tworzyć chainowane wywołania metod, pozwalając developerowi na utworzenie użytkownika i natychmiastowe wywołanie wygenerowanej metody do pobrania profilu na zwróconym obiekcie. I tu jest kluczowa sprawa. Prawdziwa siła obiektu Link polega na tym, że zasypuje on przepaść między odizolowanymi endpointami, zamieniając płaski słownik ścieżek API w nawigowalną mapę akcji, za którymi twoi klienci mogą pewnie podążać bez polegania na zahardkodowanych URL-ach. Dzięki za wysłuchanie — do usłyszenia następnym razem.

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 15 z 19. Idealnie przygotowana specyfikacja JSON jest bezużyteczna, jeśli developerzy konsumujący twoje API nie chcą jej czytać. Musisz ją zwizualizować. Właśnie tutaj do gry wchodzą interaktywne dokumenty ze Swagger UI. Do tej pory traktowaliśmy dokument OpenAPI jako surowy plik tekstowy zawierający endpointy i schematy. Swagger UI bierze ten plik JSON lub YAML i przekształca go w interaktywną stronę internetową. To przenosi cały środek ciężkości z pisania specyfikacji na jej aktywne konsumowanie. Developerzy mogą przeglądać endpointy, sprawdzać query parameters i wykonywać requesty HTTP na żywo bezpośrednio z przeglądarki. Działa to jako pomost między statycznym kontraktem a narzędziem do testowania na żywo. Jeśli chcesz hostować ten interfejs samodzielnie, prawdopodobnie zaczniesz od Node Package Manager. Kiedy przejdziesz do instalacji, od razu natkniesz się na typową pułapkę w nazewnictwie. Istnieją dwa główne pakiety. Pierwszy nazywa się po prostu swagger myślnik ui. Nie używaj go, chyba że używasz build toola, takiego jak Webpack lub Rollup, żeby skompilować customową aplikację front-endową. Jeśli twoim celem jest po prostu bezpośrednie hostowanie dokumentacji, potrzebujesz pakietu o nazwie swagger myślnik ui myślnik dist. Sufiks dist oznacza distribution. Zawiera on zbuildowane, gotowe do zaserwowania statyczne assety, takie jak główne bundle JavaScript, arkusze stylów CSS i plik index HTML. Wrzucasz te pliki na dowolny prosty serwer WWW i działają one natychmiast. Jeśli w ogóle nie chcesz zarządzać paczkami node'a ani plikami lokalnymi, możesz osadzić dokładnie te same statyczne assety na pustej stronie internetowej, używając Content Delivery Network, takiego jak unpkg. Dodajesz standardowy tag style w HTML wskazujący na plik CSS Swagger UI na unpkg, oraz tag script dla bundla JavaScript. Następnie piszesz krótki blok inicjalizacyjny w JavaScript, który wskazuje na adres webowy, pod którym znajduje się twój plik OpenAPI. Przeglądarka ładuje pustą stronę, dociąga assety z sieci, pobiera twoją specyfikację i automatycznie renderuje cały interfejs. Oto kluczowa sprawa. Nie musisz nawet pisać HTML-a, żeby zdeployować ten interfejs. Najczystszą i najbardziej skalowalną metodą jest użycie oficjalnego obrazu Dockera. Po prostu pullujesz obraz o nazwie swaggerapi slash swagger myślnik ui. Uruchomienie go całkowicie out of the box załaduje domyślny przykład Petstore. Żeby zamiast tego serwować swój własny plik lokalny, montujesz swoją specyfikację w kontenerze jako volume. Następnie przekazujesz zmienną środowiskową o nazwie SWAGGER podłoga JSON, wskazującą na dokładną ścieżkę, pod którą zamontowałeś ten plik wewnątrz kontenera. Najpierw wykonujesz komendę Docker run i mapujesz wystawiony port, na przykład osiemdziesiąt, na swoją maszynę lokalną. Następnie mapujesz swój lokalny katalog zawierający plik swagger kropka json na katalog wewnątrz kontenera. Na koniec ustawiasz zmienną środowiskową SWAGGER podłoga JSON tak, aby wskazywała na tę konkretną wewnętrzną ścieżkę do pliku. Kiedy kontener wystartuje, podnosi lekki serwer WWW, odczytuje twoją zmienną środowiskową, żeby zlokalizować specyfikację, i serwuje UI. Otrzymujesz w pełni funkcjonalny portal z dokumentacją, działający w kilka sekund, bez instalowania ani jednej lokalnej zależności. Dzięki odseparowaniu renderowania dokumentacji od samego kodu źródłowego API, Swagger UI zamienia statyczny kontrakt tekstowy w wykonywalne środowisko testowe, które płynnie przenosi się pomiędzy dowolną infrastrukturą. Dzięki za spędzenie ze mną tych kilku minut. Do usłyszenia następnym razem, trzymaj się.

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swagger, odcinek 16 z 19. Twoja dokumentacja API ładuje się dziesięć sekund, a za każdym razem, gdy inżynier chce pokazać koledze konkretny endpoint, musi ręcznie pisać instrukcję, jak przewinąć w dół i go znaleźć. Domyślne ustawienia są po to, aby je zmienić. Dostosujmy interfejs, żeby twoi developerzy znajdowali dokładnie to, czego potrzebują, w milisekundach. W tym odcinku chodzi o customizację Swagger UI. Zanim cokolwiek zmienimy, musimy postawić wyraźną granicę. Ustawienia, o których mówimy, nie lądują w twoim dokumencie specyfikacji OpenAPI. To są konfiguracje runtime. Modyfikujesz interfejs, który renderuje dokument, a nie sam dokument. Wstrzykujesz te parametry na jeden z dwóch sposobów. Jeśli sam hostujesz pliki UI, przekazujesz obiekt konfiguracji do konstruktora JavaScript w Swagger UI podczas ładowania strony. Jeśli używasz oficjalnego obrazu Dockera dla Swagger UI, przekazujesz dokładnie te same właściwości bezpośrednio do kontenera jako zmienne środowiskowe. Najbardziej podstawowe ustawienie mówi interfejsowi, gdzie znaleźć twoją specyfikację. Jeśli masz jedno API, używasz parametru o nazwie url, w liczbie pojedynczej, i przekazujesz mu ścieżkę jako string. Ale jeśli masz architekturę mikroserwisów z wieloma różnymi API, używasz parametru urls, w liczbie mnogiej. Przekazujesz mu tablicę zawierającą obiekty, z których każdy ma nazwę i link. To automatycznie generuje dropdown w górnym pasku interfejsu, pozwalając użytkownikowi płynnie przełączać się między różnymi definicjami API. Wyobraź sobie teraz ogromne, korporacyjne API z setkami ścieżek i złożonymi modelami danych. Jeśli Swagger UI spróbuje wyrenderować to wszystko na ekranie naraz, przeglądarka się zawiesi. Parametr, który to kontroluje, to docExpansion. Domyślnie jest on ustawiony na słowo list, co rozwija wszystkie tagi najwyższego poziomu, ale ukrywa szczegóły operacji. Możesz zmienić to na full, co rozwija absolutnie wszystko na stronie. Jednak, żeby zaoszczędzić czas ładowania przy ogromnym API, powinieneś ustawić docExpansion na none. To wymusza załadowanie interfejsu w stanie całkowicie zwiniętym. Oszczędza to mnóstwo pamięci i renderuje się natychmiast, pozwalając użytkownikowi otworzyć tylko to, czego faktycznie potrzebuje. Gdy użytkownik znajdzie to, czego potrzebuje, będzie chciał się tym podzielić. Domyślnie, przeklikiwanie się przez operacje w Swagger UI nie zmienia paska adresu przeglądarki. Jeśli ustawisz parametr deepLinking na true, interfejs doklei fragment z hashem do URL-a za każdym razem, gdy użytkownik rozwinie endpoint lub tag. Twoi developerzy mogą skopiować ten konkretny URL i wysłać go koledze, przenosząc go dokładnie do określonej operacji, zamiast na samą górę strony. I tu jest kluczowa kwestia. Jeśli twoja dokumentacja służy głównie jako sandbox, chcesz zminimalizować tarcie. Zazwyczaj użytkownik musi kliknąć przycisk Try it out przy operacji, aby odblokować pola wejściowe. Jeśli ustawisz flagę tryItOutEnabled na true, te pola wejściowe będą aktywne w momencie rozwinięcia operacji. Użytkownik może po prostu wpisywać dane i klikać execute bez tego dodatkowego kliknięcia. Customizacja Swagger UI w runtime daje ci moc kształtowania doświadczeń z dokumentacją wokół intencji użytkownika, przekształcając generyczne renderowanie w wydajne narzędzie skrojone pod twój zespół. Dzięki za wysłuchanie. Trzymajcie się.

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 17 z 19. Ręczne pisanie specyfikacji OpenAPI w standardowym edytorze tekstu to koszmar literówek i źle wyrównanych nawiasów. Potrzebujesz środowiska, które nakrzyczy na ciebie w ułamku sekundy, gdy tylko zrobisz złe wcięcie w pathu. I to właśnie daje ci projektowanie w Swagger Editor. Swagger Editor to nie tylko zwykłe pole tekstowe. To zintegrowane środowisko programistyczne, czyli IDE, stworzone specjalnie dla standardu OpenAPI. Jego głównym zadaniem jest pomoc w projektowaniu, definiowaniu i dokumentowaniu twojego API od podstaw. Interfejs jest podzielony na dwie części. Po lewej stronie masz swój surowy kod YAML lub JSON. Po prawej stronie widzisz wyrenderowaną, interaktywną dokumentację. I tu jest kluczowa sprawa. Edytor waliduje twoją składnię ze specyfikacją OpenAPI w czasie rzeczywistym. Jeśli zrobisz literówkę w nazwie obiektu albo zapomnisz o wymaganym polu, natychmiast oflaguje błąd i powie ci dokładnie, w której linijce jest problem. Nie musisz odpalać osobnego skryptu budującego, żeby dowiedzieć się, że masz rozjechane wcięcia. Musimy sobie coś wyjaśnić w kwestii wersji. Klasyczny Swagger Editor, znany jako wersja 4, to już narzędzie legacy. W pełni wspiera OpenAPI 2.0 i 3.0. Nie został natywnie zbudowany dla OpenAPI 3.1.0. Jeśli wkleisz specyfikację 3.1.0 do klasycznego edytora, walidacja po prostu nie przejdzie. W przypadku nowoczesnych specyfikacji 3.1.0 musisz przesiąść się na Swagger Editor Next, który omówimy w finale. Ale przy standardowej pracy z wersją 3.0, klasyczny edytor wciąż pozostaje głęboko osadzony w wielu workflowach. Możesz używać klasycznego edytora bezpośrednio w przeglądarce, bez instalowania czegokolwiek. Jednak wklejanie zastrzeżonych projektów API na publiczną stronę to szybki sposób na wkurzenie twojego zespołu security. I tutaj wkracza uruchamianie lokalne. Możesz odpalić Swagger Editor lokalnie na własnej maszynie. Możesz go zainstalować przez npm, pobierając paczkę swagger-editor i uruchamiając lokalny serwer. Jeszcze czystszym podejściem jest użycie Dockera. Pullujesz obraz swaggerapi slash swagger-editor i odpalasz kontener zmapowany na twój lokalny port. To uruchamia dokładnie ten sam edytor wizualny w całości na twojej maszynie. Taki setup pozwala zespołom na bezpieczne projektowanie za korporacyjnym firewallem, bez wystawiania nieopublikowanych specyfikacji do publicznego internetu. Cała walidacja w czasie rzeczywistym odbywa się lokalnie. Ponieważ edytor daje natychmiastowy wizualny feedback, projektujesz szybciej. Mapujesz swoje pathy, definiujesz modele danych i od razu weryfikujesz, czy wynikowa dokumentacja ma sens. Wyłapujesz błędy strukturalne już na etapie projektowania, na długo przed napisaniem logiki backendu. Jeśli uważasz te odcinki za pomocne, możesz wesprzeć podcast, wyszukując DevStoriesEU na Patreonie. Najbardziej wartościowym aspektem edytora jest natychmiastowa pewność, którą ci daje; wolna od błędów specyfikacja na ekranie gwarantuje, że twoje narzędzia downstream będą działać bez problemu. To wszystko w tym odcinku. Dzięki za słuchanie i buduj dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 18 z 19. Spędziłeś godziny na projektowaniu idealnej specyfikacji. Teraz zobacz, jak w trzy sekundy pisze za ciebie tysiące linii kodu serwera. To jest właśnie nagroda za automatyzację ze Swagger Codegen. Najpierw musimy wyjaśnić częstą pułapkę związaną z wersjonowaniem. Swagger Codegen w wersji drugiej obsługuje wyłącznie starsze specyfikacje Swagger 2.0. Jeśli korzystasz z nowoczesnego standardu OpenAPI 3.0, musisz użyć Swagger Codegen w wersji trzeciej. Ten odcinek skupia się wyłącznie na wersji trzeciej. Swagger Codegen to oparty na szablonach silnik, który czyta twój dokument OpenAPI i automatycznie buduje kod aplikacji. Tłumaczy twoje pliki projektowe na rzeczywiste klasy, interfejsy i operacje sieciowe. To jest największa nagroda za podejście design-first. Zamiast ręcznie pisać setki plików boilerplate'owych dla routingu HTTP, parsowania parametrów i modeli obiektów, pozwalasz maszynie zająć się powtarzalną pracą. Generator tworzy dwa główne typy kodu. Po pierwsze, buduje klienckie SDK. Jeśli potrzebujesz klienta w Pythonie, JavaScripcie lub Go do komunikacji z twoim API, Codegen tworzy gotową do użycia bibliotekę. Pakiet kliencki automatycznie obsługuje requesty HTTP, formatowanie URL-i oraz parsowanie odpowiedzi. Frontend developerzy lub inne zespoły od mikrousług mogą po prostu zaimportować tę wygenerowaną bibliotekę i natywnie wywoływać metody, zamiast ręcznie pisać requesty sieciowe. Po drugie, generuje stuby serwera. Taki stub serwera to strukturalny szkielet twojej aplikacji backendowej. Zawiera routing API, modele danych i warstwy walidacji wejścia. Spina wszystko razem, dzięki czemu serwer może od razu wystartować i nasłuchiwać ruchu. Wygenerowany kod przechwytuje przychodzące requesty HTTP, waliduje payload z twoim schematem OpenAPI i przekazuje czyste dane do pustej funkcji. Twoim jedynym zadaniem jako developera jest wypełnienie tych pustych funkcji właściwą logiką biznesową, taką jak zapytania do bazy danych czy obliczenia. Przejdźmy przez to, jak właściwie to uruchomić. Swagger Codegen jest zazwyczaj uruchamiany z poziomu CLI przy użyciu pliku archiwum Javy. Otwierasz terminal i odpalasz polecenie java z flagą minus jar, wskazując na plik swagger-codegen-cli kropka jar. Przekazujesz mu polecenie generate. Następnie podajesz trzy niezbędne flagi. Używasz minus i, aby określić plik wejściowy, na przykład openapi kropka yaml. Używasz minus l, aby ustawić docelowy język i framework. Na przykład, przekazanie spring mówi narzędziu, żeby zbudowało aplikację w Java Spring Boot. Na koniec używasz minus o, aby określić docelowy katalog wyjściowy. Uruchamiasz polecenie. W kilka sekund narzędzie parsuje specyfikację. Mapuje każdy string, integer i array zdefiniowany w twoim dokumencie OpenAPI na odpowiednie natywne typy w Javie. Opiera się na bibliotece gotowych szablonów logiki dla docelowego frameworka, aby spiąć te typy ze sobą. W rezultacie otrzymujesz kompletną strukturę katalogów wypełnioną kontrolerami, plikami konfiguracyjnymi i klasami danych. Możesz od razu skompilować ten katalog wyjściowy, wystartować serwer i z powodzeniem uderzyć w zaprojektowane endpointy. I tu jest kluczowa sprawa. Generowanie kodu nie tylko oszczędza czas na starcie. Generując strukturę serwera i biblioteki klienckie bezpośrednio z tego samego pliku OpenAPI, gwarantujesz, że twoja implementacja idealnie pasuje do kontraktu, redukując błędy integracyjne między zespołami do zera. To wszystko w tym odcinku. Dzięki za wysłuchanie i twórz dalej!

Cześć, tu Alex z DEV STORIES DOT EU. OpenAPI i ekosystem Swaggera, odcinek 19 z 19. REST API nie są już jedynym sposobem komunikacji systemów. Czas na narzędzie, które rozumie Kafkę i architektury event-driven równie dobrze, co HTTP. Tym narzędziem jest Swagger Editor Next. Znany również jako wersja piąta, to kompletna przebudowa standardowego interfejsu, który możesz już znać. Klasyczny Swagger Editor jest mocno powiązany z synchronicznymi HTTP API i starszymi technikami renderowania. Działa dobrze z OpenAPI 3.0, ale potrafi się zawiesić lub lagować podczas walidacji wyjątkowo dużych plików. Swagger Editor Next zastępuje tę starzejącą się infrastrukturę. Został w całości zbudowany na nowoczesnym stacku Reacta i Webpacka. I to jest najważniejsze. Główny text input jest teraz napędzany przez Monaco Editor. To dokładnie ta sama technologia, która napędza Visual Studio Code. Dzięki temu, że opiera się na Monaco, Swagger Editor Next radzi sobie z ogromnymi plikami specyfikacji bez żadnych zacięć. Zapewnia solidny syntax highlighting, natychmiastowe wykrywanie błędów i precyzyjną walidację na poziomie konkretnej linii, co po prostu deklasuje klasyczną wersję. W praktyce piszesz w lekkim IDE, a nie w zwykłym formularzu na stronie. Tyle jeśli chodzi o silnik. A co z samymi specyfikacjami? Swagger Editor Next wprowadza dwie główne, natywne funkcje. Po pierwsze, wspiera OpenAPI 3.1.0 out of the box. Ta konkretna wersja OpenAPI jest w pełni zgodna z JSON Schema, co oznacza, że możesz budować znacznie bardziej złożone modele danych i reużywalne komponenty niż w wersji 3.0. Po drugie, Swagger Editor Next natywnie renderuje specyfikacje AsyncAPI. To zdecydowanie krok naprzód dla developerów, którzy tworzą mikroserwisy event-driven obok tradycyjnych API. AsyncAPI używa struktury bardzo podobnej do OpenAPI, ale zamiast definiować ścieżki HTTP i requesty GET, dokumentuje message brokery, topiki i zdarzenia asynchroniczne. Aby zobaczyć, jak to działa w praktyce, wyobraź sobie sieć smart city zarządzającą oświetleniem ulicznym. Gdybyś miał tylko narzędzia do RESTa, mógłbyś próbować zmusić endpoint HTTP POST do reprezentowania ciągłego strumienia danych z sensorów. Ze Swagger Editor Next po prostu piszesz dokument AsyncAPI. Definiujesz kanał o nazwie smart-city-streetlights. Przypisujesz Kafkę jako protokół. Następnie określasz operację publish, szczegółowo opisując dokładną strukturę JSON, którą emituje sensor, gdy włącza się światło. Kiedy wpisujesz specyfikację po lewej stronie ekranu, Monaco Editor waliduje składnię AsyncAPI. Po prawej stronie interfejs renderuje ustrukturyzowany, interaktywny dokument wizualny. Przejrzyście wyświetla topiki Kafki, oczekiwane payloady wiadomości i nagłówki protokołu. Nie potrzebujesz już oddzielnych toolchainów dla swoich synchronicznych API i mikroserwisów event-driven. Ekosystem ewoluował, aby obsługiwać oba te elementy jednocześnie. Przejście na zdarzenia asynchroniczne nie oznacza zaczynania dokumentacji od zera; wymaga jedynie nowoczesnego edytora, który potrafi odczytać te nowe standardy. Jako że to podsumowanie naszej serii, poświęć chwilę na przeczytanie oficjalnej dokumentacji, odpal Swagger Editor Next i spróbuj samodzielnie zamodelować topik Kafki. Jeśli masz pomysł na zupełnie nową serię, wejdź na devstories dot eu i daj nam znać. To wszystko w tym odcinku. Do usłyszenia następnym razem!