Generator plików HTTP: Testowanie API przy użyciu plików .http

Zwiększ wydajność testowania API: jak pliki .http w Twoim środowisku IDE mogą zrewolucjonizować Twój proces pracy dzięki generatorowi plików http.

Wykorzystaj pełen potencjał plików .http, aby usprawnić testowanie REST API w swoim środowisku IDE. Dowiedz się, jak to proste, ale potężne podejście zwiększa produktywność, wspiera współpracę i płynnie integruje się z Twoim projektem API. Przedstawimy również nasz generator plików http, który łączy istniejące pliki .http, zachowując Twoje dane niestandardowe, oraz pokażemy, jak można go zintegrować z OpenAPI (Swagger UI) lub odwołaniami do plików specyfikacji openapi. Ponadto omówimy integrację oprogramowania pośredniczącego Swagger oraz konfigurację niezbędną do obsługi wygenerowanego pliku JSON zawierającego dokumentację API.

Wprowadzenie do testowania API

Testowanie API to kluczowy etap w zapewnianiu jakości i niezawodności internetowych interfejsów API. Obejmuje ono sprawdzenie, czy API działa zgodnie z oczekiwaniami, zwraca prawidłowe dane i odpowiednio obsługuje błędy. Testowanie API można przeprowadzać ręcznie lub przy użyciu zautomatyzowanych narzędzi, a dokładne testowanie API jest niezbędne, aby wykryć wszelkie błędy lub problemy, zanim trafią one do środowiska produkcyjnego.

W tej sekcji przedstawimy podstawy testowania API, w tym różne rodzaje testów API, stosowane narzędzia i techniki oraz korzyści płynące z testowania API. Omówimy również znaczenie testowania API w różnych środowiskach oraz rolę testowania API w cyklu życia oprogramowania.

Czym są pliki .http?

(na górnym obrazku pliki http wygenerowane z biblioteki z wynikami działania w środowisku Visual Studio 2022 IDE)

(na górnym obrazku pliki http wygenerowane z biblioteki z wynikami działania w środowisku Jetbrains Rider IDE)

Plik .http to plik tekstowy zawierający wiele żądań (takich jak GET, POST, PUT, DELETE), które można wykonać bezpośrednio z poziomu środowiska IDE. Zamiast korzystać z wielu narzędzi zewnętrznych, wszystkie testy API przechowujesz tuż obok kodu w systemie kontroli wersji. Na przykład: http

GET https://example.com/api/products Authorization: Bearer {{token}} ### POST https://example.com/api/products Content-Type: application/json { “name”: “Widget”, “price”: 9.99 }

Odwołania do specyfikacji OpenAPI i zaawansowane tagi mogą dodatkowo pomóc w definiowaniu punktów końcowych, ale plik .http działa zarówno z formalną specyfikacją OpenAPI, jak i bez niej. Elementy OpenAPI pomagają w organizowaniu i dodawaniu nowych elementów, usprawniając proces testowania API.

Korzystanie z plików .http podczas tworzenia oprogramowania

Kluczowe korzyści

1. Brak konieczności przełączania się do zewnętrznych aplikacji w celu testowania: wszystko działa w Twoim środowisku IDE.
2. Łatwa współpraca: dodawaj pliki .http do Git. Każde zatwierdzenie pokazuje nowe lub zmienione żądania.
3. Obsługuje symbole zastępcze środowiska, nagłówek autoryzacji, parametry zapytania i treści żądań, co pozwala na szybkie aktualizacje.

Kontrola wersji i obsługa tajnych danych

• Wprowadź swoje pliki .http, ale wyklucz prywatne ustawienia środowiska:
  • W Visual Studio sekrety można umieścić w pliku http-client.env.json.user, który następnie dodajesz do .gitignore.
  • W Riderze sekrety użytkownika mogą znajdować się w pliku http-client.private.env.json (również .gitignore).
• Zapobiega to przypadkowemu przesłaniu tokenów, kluczy API lub innych poświadczeń.

Praca z plikami .http w różnych środowiskach IDE

Przed użyciem generatora plików http musisz zainstalować rozszerzenie w Visual Studio Code. Visual Studio 2022 i Rider mają wbudowaną obsługę.

Każde środowisko IDE ma własne wymagania dotyczące zastępowania tajnych kluczy. Biblioteka automatycznie wygeneruje szablony zarówno dla Visual Studio, jak i Ridera.

Rozszerzenie Visual Studio Code

1. Zainstaluj rozszerzenie REST Client dla Visual Studio Code ze sklepu Marketplace.
2. Utwórz plik o nazwie requests.http.
3. Wpisz swoje żądania i naciśnij „Wyślij żądanie” w palecie poleceń lub z linku wbudowanego.
4. Użyj okna podglądu, aby wyświetlić specyfikacje API w rozszerzeniu Visual Studio Code.
5. Dodaj plik .env lub zmienne środowiskowe dla swoich tokenów, aby nie umieszczać ich w pliku .http.

JetBrains Rider / WebStorm

• Wbudowana obsługa żądań z pliku .http.
• Dane środowiskowe można przechowywać w pliku .env lub w oddzielnych plikach tymczasowych.
• Rider używa pliku http-client.private.env.json dla zmiennych tajnych (takich jak token dostępu).

Visual Studio

• Zawiera podstawową integrację z plikami .http.
• Utwórz nowy plik z rozszerzeniem .http, wpisz swoje żądania i uruchom je za pomocą wbudowanej funkcji. Ponadto integracja z VS Code oferuje funkcje audytu i obsługę IntelliSense, poprawiając komfort programowania.

Automatyczne generowanie i aktualizowanie plików .http

Instalowanie pakietu NuGet

Jeśli chcesz automatycznie generować lub aktualizować pliki .http z poziomu projektu API sieci Web:

Otwórz konsolę menedżera pakietów

Install-Package ITBees.WebApiHttpFilesGenerator

Przywróć pakiety, aby upewnić się, że wszystko jest zainstalowane

Kluczowe funkcje i zachowanie podczas scalania

• Przeszukuje kontrolery pod kątem [HttpGet], [HttpPost], [HttpPut], [HttpDelete] (w tym zaawansowanych przykładów, takich jak [HttpDelete(„{id}”)]).
• Tworzy lub łączy się z istniejącym plikiem .http dla każdego kontrolera. Plik OpenAPI odgrywa kluczową rolę w zwiększaniu funkcjonalności i bezpieczeństwa API, w tym w generowaniu konfiguracji skanowania do testów bezpieczeństwa.
• Zachowuje wcześniej wprowadzone dane, parametry zapytania lub treści żądań JSON.
• Brak nadpisywania, jeśli pola nadal istnieją w sygnaturze metody.
• Działa dobrze z plikiem specyfikacji OpenAPI, jeśli zweryfikujesz definicje schematów.

Zaawansowany przykład z Twoim projektem API sieci Web

Zapoznaj się z naszym przykładowym projektem na GitHubie

Możesz sprawdzić projekt HelloWorldApi gotowy do przetestowania tego rozwiązania na GitHubie.

Włączenie generatora do kodu startowego

W pliku Program.cs lub podobnym punkcie wejścia można skonfigurować generator tak, aby uruchamiał się automatycznie w określonych środowiskach (spowoduje to ponowne wygenerowanie plików podczas uruchamiania aplikacji w środowisku programistycznym):

// Configure the HTTP request pipeline.
if (builder.Configuration.GetSection("Environment").Value == "dev" || builder.Configuration.GetSection("Environment").Value == "uat")
{
    app.UseSwagger();
    app.UseSwaggerUI();
    HttpFilesGenerator.RegenerateHttpFiles(typeof(MyProject.MySampleService).Assembly, "C:\\Users\\user\\source\\repos\\MyProject\\WebApiProject\\", "HttpApi");
}

Lub w uproszczonej wersji, jeśli domyślny folder dla wygenerowanych plików znajduje się w uruchomionym projekcie.

Ten fragment kodu gwarantuje, że jeśli znajdujesz się w środowisku deweloperskim lub UAT, również:

• Włączysz Swagger (tj. interfejs użytkownika Swagger).
• Automatycznie wygenerujesz lub zaktualizujesz pliki .http w folderze HttpApi.

Obsługa OpenAPI, Swagger UI i elementów ścieżki

• Jeśli Twój projekt API sieci Web zawiera Swagger UI lub przeglądarkę OpenAPI, możesz łatwo porównać nowe pliki .http z wynikami specyfikacji OpenAPI.
• Pomaga to zapewnić zgodność dokumentacji z rzeczywistymi metodami i żądaniami widocznymi w plikach .http.

Testowanie bezpieczeństwa API

Testowanie bezpieczeństwa API to kluczowy aspekt testowania API, który polega na identyfikowaniu luk i słabych punktów w mechanizmach bezpieczeństwa API. Ten rodzaj testów pomaga zapewnić, że API jest bezpieczne i chronione przed typowymi atakami internetowymi, takimi jak wstrzyknięcie kodu SQL, skrypty międzywitrynowe (XSS) i fałszowanie żądań międzywitrynowych (CSRF).

W tej sekcji omówimy różne rodzaje testów bezpieczeństwa API, w tym testy uwierzytelniania i autoryzacji, testy walidacji danych wejściowych oraz testy obsługi błędów. Omówimy również narzędzia i techniki stosowane do testowania bezpieczeństwa API, takie jak testy penetracyjne, skanowanie podatności i audyty bezpieczeństwa.

Testowanie plików .http w różnych środowiskach przy użyciu generatora plików http

Testowanie plików .http w różnych środowiskach jest niezbędne do zapewnienia prawidłowego działania API w różnych scenariuszach. Obejmuje to testowanie API w różnych systemach operacyjnych, przeglądarkach i urządzeniach, a także testowanie API z różnymi danymi wejściowymi i przypadkami skrajnymi.

W tej sekcji omówimy różne środowiska, w których można testować pliki .http, w tym lokalne środowiska programistyczne, środowiska stagingowe i produkcyjne. Omówimy również narzędzia i techniki stosowane do testowania plików .http w różnych środowiskach, takie jak konteneryzacja, wirtualizacja i testowanie w chmurze.

Pliki sekretów i środowisk

Visual Studio: http-client.env.json.user

Należy pamiętać, że wszystkie wartości określone w pliku http-client.env.json.user zastąpią wartości w pliku http-client.env.json.

• W Visual Studio można umieścić tokeny sekretne, zmienne środowiskowe (takie jak tokeny Bearer) lub inne poświadczenia w pliku o nazwie http-client.env.json.user
• Dodaj ten plik do .gitignore, aby nigdy nie trafił do kontroli źródła.
• W czasie wykonywania żądania HTTP mogą odwoływać się do tych kluczy za pomocą {{secretValue}}.

Rider: http-client.private.env.json

Należy pamiętać, że wszystkie wartości określone w pliku http-client.private.env.json zastąpią wartości w pliku http-client.env.json.

• W JetBrains Rider zmienne środowiskowe lub poufne dane uwierzytelniające można umieścić w pliku http-client.private.env.json.
• Podobnie, ze względów bezpieczeństwa nie umieszczaj go w Git.
• Plik .http odwołuje się do tych zmiennych, umożliwiając testowanie przy minimalnych zmianach ręcznych.

Dzięki temu plik .http pozostaje w pełni udostępnialny, a poufne dane są przechowywane wyłącznie w lokalnych plikach środowiskowych.

10. Rozwiązywanie problemów i obsługa błędów

Rozwiązywanie problemów i obsługa błędów to kluczowe aspekty testowania API, które obejmują identyfikację i rozwiązywanie problemów pojawiających się podczas testów. Obejmuje to debugowanie błędów, obsługę wyjątków oraz rejestrowanie błędów w celu dalszej analizy.

W tej sekcji omówimy różne techniki stosowane w rozwiązywaniu problemów i obsłudze błędów, w tym narzędzia do debugowania. Omówimy również rejestrowanie błędów i obsługę wyjątków. Omówimy również znaczenie obsługi błędów w testowaniu API oraz to, w jaki sposób może ona pomóc w poprawie ogólnej jakości i niezawodności API.

Najlepsze praktyki i końcowe przemyślenia dotyczące generatora plików http

1. Przechowuj pliki .http w systemie kontroli wersji, ale wyklucz dane osobowe lub poufne dotyczące środowiska (pliki .user lub .private).

1. Użyj logiki scalania generatora, aby zapewnić automatyczne pojawianie się nowo dodanych metod. Ważne jest, aby stare pola pozostały, jeśli nadal istnieją w kodzie.
2. Połącz pliki .http z plikiem specyfikacji openapi, aby uzyskać lepszą zgodność.
3. Jeśli w Twoim REST API pojawią się zmiany lub dodasz nowe treści żądań lub schematy, uruchom generator, aby zaktualizować żądania testowe.
4. Synergia plików .http, interfejsu użytkownika Swagger oraz elementów OpenAPI może radykalnie poprawić komfort pracy programisty. Odbywa się to poprzez umożliwienie płynnego generowania żądań, szybkiego ich testowania oraz dokładnego śledzenia zmian w Git.

Wypróbuj to i ciesz się szybszymi pętlami informacji zwrotnej, prostszą obsługą zabezpieczeń oraz bardziej opartym na współpracy podejściem do tworzenia API. Dzięki generatorowi plików http w swoim procesie szybko przekonasz się, jak pliki .http mogą stać się nieocenionym rozszerzeniem codziennego przepływu pracy przy kodowaniu.

Dodatkowe zasoby

W tej sekcji przedstawimy dodatkowe zasoby dotyczące testowania API, w tym książki, artykuły i kursy online. Omówimy również różne narzędzia i frameworki dostępne do testowania API, w tym Swagger UI, Visual Studio Code i pliki OpenAPI.

Niektóre popularne narzędzia i frameworki do testowania API to:

• Swagger UI: popularne narzędzie do dokumentacji i testowania API
• Visual Studio Code: popularny edytor kodu do tworzenia i testowania API
• Pliki OpenAPI: standardowy format dokumentacji i testowania API
• JSON HTTP Generator: narzędzie do generowania żądań HTTP w formacie JSON
• HTTP File Generator: narzędzie do generowania plików .http na podstawie specyfikacji OpenAPI

Mamy nadzieję, że to pomoże! Daj znać, jeśli potrzebujesz dalszej pomocy – help@itbees.pl lub zostaw komentarz tutaj.

Jakub Zohar Rutkowski