04-07-2022

Generowanie klienta HTTP na podstawie OpenAPI

Share

Na temat tworzenia REST API powstało już wystarczająco dużo artykułów. Pozostaje natomiast pytanie, jak szybko wygenerować klienta, który będzie odpowiadał naszym wymaganiom? Aby osiągnąć ten cel powinniśmy posiadać standard, który pozwoli stworzyć schemat stworzonych przez nas metod. Z pomocą przychodzi OpenAPI.

Co to jest OpenAPI?

Jak mówi dokumentacja, OpenAPI to standard niezależny od języka programowania, który opisuje REST API w sposób czytelny dla komputerów i ludzi bez dostępu do kodu źródłowego. Opis metod serwera zawiera się w pliku YAML lub JSON. W tym artykule nie będę poruszał schematu pliku.

OpenAPI w .NET Core

W przypadku .NET Core, aby wygenerować specyfikację API musimy posłużyć się zewnętrznymi bibliotekami. Nie ma znaczenia jakiej użyjemy, bo OpenAPI ma swój standard i każda biblioteka powinna generować schemat według ściśle określonych zasad. W naszych projektach najczęściej używamy biblioteki Swashbuckle. Jest bardzo prosta w konfiguracji. Więcej na ten temat możecie poczytać na stronie:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore

Zastosowania OpenAPI

Najpowszechniejszym zastosowaniem schematu metod naszego serwera jest klient Swagger, który jest najczęściej wystawiany razem z naszą aplikacją. Swagger dostarcza prosty interfejs, w którym możemy podejrzeć parametry wejściowe, model wyjściowy i wykonać zapytania do serwera. Przede wszystkim, ułatwia to na pewno proces tworzenia lub testowania naszego API, ale my pójdziemy o krok dalej. W ramach artykułu stworzymy klienta w .NET Core.

W ramach procesu tworzenia nowego produktu potrzebowaliśmy możliwości szybkiego testowania naszego serwisu. Przy kilku wdrożeniach na dzień musieliśmy zautomatyzować proces testów. Nie mogliśmy poświęcać dużo czasu na aktualizowanie kodu klienta w projekcie testowym.

Generowanie klienta

Dosyć teorii. Napiszmy jakiś kod 🙂 Do generowania używamy narzędzia NSwag. Aby rozpocząć pracę tworzymy nowy projekt, dzięki poniższym komendom.

dotnet new xunit -n Esky.OpenApiClientTests
dotnet new tool-manifest
dotnet tool install NSwag.ConsoleCore
dotnet tool run nswag new

W następnym kroku dodajemy plik konfiguracyjny zawierający narzędzia, które są do użytku w ramach projektu oraz instalujemy je lokalnie i tworzymy nową konfigurację – nswag.json. Dla użytkowników systemu Windows konfiguracja tego pliku jest dosyć prosta. Twórca udostępnia darmowy program, dzięki któremu możemy poustawiać wszystkie właściwości idealnie dla siebie. Niestety w przypadku innych systemów operacyjnych musimy poradzić sobie z json ręcznie.

code nswag.json

Otwieramy nasz plik konfiguracyjny w ulubionym edytorze kodu. Niestety nie ma dobrej dokumentacji schematu tego pliku, musimy sami znaleźć odpowiednią konfigurację. Na końcu artykułu załączam przykładowy projekt, w którym znajdziecie konfigurację spełniającą nasze wymagania.

Załóżmy, że mamy już idealnie przygotowany plik. Co teraz?

dotnet tool run nswag run ./nswag.json

Generujemy gotowego do użycia klienta. Do sprawdzenia stworzonego kodu napiszemy prosty test:

public class SimpleTests
{
private readonly PetClient _petClient = new(new HttpClient()
    {        
BaseAddress = new Uri("https://petstore.swagger.io/v2/")
});
    [Fact]    
public async Task Should_Return_Pets()  
{
var pets = await _petClient.FindByStatusAsync(new[] {
Anonymous.Available }, CancellationToken.None);
Assert.NotEmpty(pets);
}

Możliwe użycie klienta

Bardzo rozbudowana konfiguracja generatora umożliwia użycie tak stworzonego klienta w prawie każdym możliwym kontekście. W naszym zespole, oprócz testów, użyliśmy tego mechanizmu na przykład do szybkiego sprawdzenia API nowego dostawcy.

Podsumowanie

Generowanie klienta HTTP na podstawie specyfikacji OpenAPI upraszcza wiele rzeczy. Dodatkowo z tak rozbudowaną konfiguracją możemy dopasować wygenerowany kod do naszych standardów (np. użycie System.Text.Json zamiast Newtonsoft.Json). Minusem jest brak dokumentacji schematu pliku json, ale miejmy nadzieje, że taki powstanie już niebawem. Konfiguracja oraz kod dostępny pod adresem: https://github.com/eskypl/simple-open-api-client