Generator plików HTTP: Testowanie API za pomocą 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ę, w jaki sposób to proste, a jednocześnie 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 udostępniania 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 weryfikację, czy API działa zgodnie z oczekiwaniami, zwraca prawidłowe dane i prawidłowo obsługuje błędy. Testowanie API można przeprowadzać ręcznie lub przy użyciu narzędzi automatycznych, 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 interfejsów 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 interfejsów 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 wraz z wynikami działania w środowisku Visual Studio 2022)

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

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. Nie musisz przełączać się do zewnętrznych aplikacji w celu testowania: wszystko działa w Twoim środowisku IDE.
2. Łatwa współpraca: dodawaj pliki .http do repozytorium Git. Każde zatwierdzenie pokazuje nowe lub zmienione żądania.
3. Obsługa symboli zastępczych środowiska, nagłówka autoryzacji, parametrów zapytania oraz treści żądań umożliwia szybkie aktualizacje.

Kontrola wersji i obsługa tajnych danych

• Wprowadzaj pliki .http do repozytorium, ale wyklucz prywatne ustawienia środowiska:
  • W Visual Studio dane poufne można umieścić w pliku http-client.env.json.user, który następnie dodajesz do pliku .gitignore.
  • W programie Rider poufne dane użytkownika można umieścić w pliku http-client.private.env.json (również w pliku .gitignore).
• Zapobiega to przypadkowemu przesłaniu tokenów, kluczy API lub innych danych uwierzytelniających.

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

Przed użyciem generatora plików http należy 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 dla Ridera.

Rozszerzenie dla 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 za pomocą linku wbudowanego.
4. Skorzystaj z 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 do przechowywania zmiennych tajnych (takich jak token dostępu).

Visual Studio

• Dostępna jest podstawowa integracja z plikami .http.
• Utwórz nowy plik z rozszerzeniem .http, wpisz żądania, a następnie uruchom je za pomocą wbudowanej funkcji. Ponadto integracja z VS Code zapewnia funkcje audytu oraz obsługę IntelliSense, poprawiając komfort programowania.

Automatyczne generowanie i aktualizowanie plików .http

Instalacja pakietu NuGet

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

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 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.
• Nie następuje nadpisywanie, 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 wykorzystaniem Twojego projektu API internetowego

Zapoznaj się z naszym przykładowym projektem na GitHubie

Na GitHubie możesz sprawdzić projekt HelloWorldApi, gotowy do przetestowania tego rozwiązania.

Włączenie generatora do kodu startowego

W pliku `Program.cs` lub podobnym punkcie wejścia możesz 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 ramach uruchomionego projektu.

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

• 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 sieciowego zawiera Swagger UI lub eksplorator 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, polegający na identyfikacji luk i słabych punktów w mechanizmach zabezpieczeń API. Ten rodzaj testów pomaga zapewnić, że API jest bezpieczne i chronione przed typowymi atakami internetowymi, takimi jak wstrzyknięcie kodu SQL (SQL injection), skrypty międzywitrynowe (XSS) oraz 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 ma kluczowe znaczenie dla zapewnienia prawidłowego działania API w różnych scenariuszach. Obejmuje to testowanie API w różnych systemach operacyjnych, przeglądarkach i na różnych urządzeniach, a także testowanie API z wykorzystaniem różnych danych wejściowych i w skrajnych przypadkach.

W tej sekcji omówimy różne środowiska, w których można testować pliki .http, w tym lokalne środowiska programistyczne, środowiska testowe i środowiska 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.

Sekrety i pliki środowiskowe

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 zawarte w pliku http-client.env.json.

• W programie Visual Studio można umieścić tokeny tajne, zmienne środowiskowe (takie jak tokeny Bearer) lub inne poświadczenia w pliku o nazwie http-client.env.json.user
• Dodaj ten plik do pliku .gitignore, aby nigdy nie trafił do kontroli wersji.
• 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 należy umieszczać go w Git.
• Plik .http odwołuje się do tych zmiennych, umożliwiając testowanie przy minimalnych ręcznych zmianach.

Dzięki temu plik .http pozostaje w pełni dostępny do udostępniania, 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, polegające na identyfikowaniu i rozwiązywaniu 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 podsumowanie 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. Wykorzystaj logikę 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. Aby zapewnić lepszą spójność, połącz pliki .http z plikiem specyfikacji OpenAPI.
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 Swagger UI 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 systemie Git.

Wypróbuj to i ciesz się szybszymi cyklami 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 pracy szybko przekonasz się, jak pliki .http mogą stać się nieocenionym rozszerzeniem Twojego codziennego procesu programowania.

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 oraz pliki OpenAPI.

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

• Swagger UI: popularne narzędzie do dokumentacji i testowania interfejsów API
• Visual Studio Code: popularny edytor kodu do tworzenia i testowania interfejsów API
• Pliki OpenAPI: standardowy format dokumentacji i testowania interfejsów 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 te informacje okażą się pomocne! Jeśli potrzebujesz dalszej pomocy, napisz do mnie na adres help@itbees.pl lub zostaw komentarz tutaj.

Jakub Zohar Rutkowski