Samouczek: generowanie klienta interfejsu API REST

Artykuł
27.01.2025

Aplikacja, która korzysta z interfejsu API REST, jest bardzo typowym scenariuszem. Zazwyczaj należy wygenerować kod klienta, którego aplikacja może używać do wywoływania interfejsu API REST. Z tego samouczka dowiesz się, jak automatycznie wygenerować klienta interfejsu API REST podczas procesu kompilacji przy użyciu programu MSBuild. Użyjesz NSwag, narzędzia, które generuje kod klienta dla interfejsu API REST.

Kompletny próbny kod jest dostępny w generowaniu klienta API REST w repozytorium przykładów platformy .NET na GitHubie.

W przykładzie pokazano aplikację konsolową, która korzysta z publicznego API Pet Store, który publikuje specyfikację OpenAPI.

W tym samouczku założono podstawową wiedzę na temat terminów MSBuild, takich jak zadania, obiekty docelowe, właściwości lub środowiska uruchomieniowe; aby zapoznać się z niezbędnymi informacjami, zobacz artykuł MSBuild Concepts (Pojęcia dotyczące programu MSBuild).

Jeśli chcesz uruchomić narzędzie wiersza polecenia w ramach kompilacji, należy wziąć pod uwagę dwa podejścia. Jednym z nich jest użycie zadania MSBuild Exec, które umożliwia uruchomienie narzędzia wiersza polecenia i określenie jego parametrów. Drugą metodą jest utworzenie niestandardowego zadania pochodzącego z ToolTask, co zapewnia większą kontrolę.

Warunki wstępne

Należy poznać pojęcia dotyczące programu MSBuild, takie jak zadania, obiekty docelowe i właściwości. Zobacz pojęcia dotyczące programu MSBuild.

Przykłady wymagają programu MSBuild zainstalowanego w programie Visual Studio, ale można go również zainstalować oddzielnie. Zobacz Pobierz program MSBuild bez programu Visual Studio.

Opcja 1: Wykonaj zadanie

Zadanie Exec po prostu wywołuje określony proces z określonymi argumentami, czeka na ukończenie, a następnie zwraca true, jeśli proces zakończy się pomyślnie, a false, jeśli wystąpi błąd.

Generowanie kodu NSwag można używać z poziomu programu MSBuild; zobacz NSwag.MSBuild.

Kompletny kod znajduje się w folderze PetReaderExecTaskExample; możesz pobrać i spojrzeć. W tym samouczku przejdziesz krok po kroku i będziesz poznawał pojęcia po drodze.

Utwórz nową aplikację konsolową o nazwie PetReaderExecTaskExample. Użyj platformy .NET 6.0 lub nowszej.
Utwórz inny projekt w tym samym rozwiązaniu: PetShopRestClient (To rozwiązanie będzie zawierać wygenerowanego klienta jako bibliotekę). W tym projekcie użyj platformy .NET Standard 2.1. Wygenerowany klient nie kompiluje się na platformie .NET Standard 2.0.
W projekcie PetReaderExecTaskExample dodaj zależność do projektu PetShopRestClient.
W projekcie PetShopRestClient uwzględnij następujące pakiety NuGet:
- Nswag.MSBuild, który umożliwia dostęp do generatora kodu z programu MSBuild
- Plik Newtonsoft.Json potrzebny do skompilowania wygenerowanego klienta
- System.ComponentModel.Annotations— wymagane do skompilowania wygenerowanego klienta
W projekcie PetShopRestClient dodaj folder (o nazwie PetShopRestClient) dla generowania kodu i usuń Class1.cs, który został wygenerowany automatycznie.
Utwórz plik tekstowy o nazwie petshop-openapi-spec.json w katalogu głównym projektu. Skopiuj specyfikację interfejsu OpenAPI z tutaj i zapisz ją w pliku. Najlepiej skopiować migawkę specyfikacji zamiast odczytywać ją w trybie online podczas kompilacji. Zawsze potrzebujesz spójnej powtarzalnej kompilacji, która zależy tylko od danych wejściowych. Korzystanie z interfejsu API bezpośrednio może przekształcić kompilację, która działa dzisiaj, w kompilację, która z tego samego źródła zawodzi jutro. Zrzut zapisany na petshop-openapi-spec.json pozwoli nam nadal mieć wersję, która zostanie skompilowana, nawet jeśli specyfikacja ulegnie zmianie.
Następnie zmodyfikuj plik PetShopRestClient.csproj i dodaj obiektów docelowych MSBuild w celu wygenerowania klienta podczas procesu kompilacji.

Najpierw dodaj kilka właściwości przydatnych do generowania klienta:

XML
```
 <PropertyGroup>
     <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation>
     <PetClientClassName>PetShopRestClient</PetClientClassName>
     <PetClientNamespace>PetShopRestClient</PetClientNamespace>
     <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory>
 </PropertyGroup>
```
Dodaj następujące cele:

XML
```
 <Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetOpenApiSpecLocation)" Outputs="$(PetClientOutputDirectory)\$(PetClientClassName).cs">
     <Exec Command="$(NSwagExe) openapi2csclient /input:$(PetOpenApiSpecLocation)  /classname:$(PetClientClassName) /namespace:$(PetClientNamespace) /output:$(PetClientOutputDirectory)\$(PetClientClassName).cs" ConsoleToMSBuild="true">
     <Output TaskParameter="ConsoleOutput" PropertyName="OutputOfExec" />
   </Exec>
 </Target>
 <Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean">
    <Delete Files="$(PetClientOutputDirectory)\$(PetClientClassName).cs"></Delete>
 </Target>
```
Zwróć uwagę, że ten element docelowy używa atrybutów BeforeTarget i AfterTarget w celu zdefiniowania kolejności kompilacji. Pierwszy element docelowy o nazwie generatePetClient zostanie wykonany przed celem kompilacji podstawowej, więc źródło zostanie utworzone przed wykonaniem kompilatora. Parametry wejściowe i wyjściowe są powiązane z kompilacją przyrostową. Program MSBuild może porównać znaczniki czasu plików wejściowych ze znacznikami czasu plików wyjściowych i określić, czy pominąć, skompilować, czy częściowo odbudować element docelowy.

Po zainstalowaniu pakietu NSwag.MSBuild NuGet w projekcie możesz użyć zmiennej $(NSwagExe) w pliku .csproj, aby uruchomić narzędzie wiersza polecenia NSwag w obiekcie docelowym MSBuild. Dzięki temu narzędzia można łatwo aktualizować za pomocą narzędzia NuGet. W tym miejscu używasz zadania Exec MSBuild, aby wykonać program NSwag z wymaganymi parametrami do wygenerowania klienta REST API. Zobacz polecenie NSwag i parametry .

Możesz przechwytywać dane wyjściowe z <Exec> poprzez dodanie ConsoleToMsBuild="true" do tagu <Exec>, a następnie przechwytywać dane wyjściowe za pomocą parametru ConsoleOutput w tagu <Output>. ConsoleOutput zwraca dane wyjściowe jako Item. Białe znaki są przycinane. ConsoleOutput jest włączona, gdy ConsoleToMSBuild ma wartość true.

Drugi cel o nazwie forceReGenerationOnRebuild usuwa wygenerowaną klasę podczas oczyszczania, aby wymusić ponowne wygenerowanie kodu przy ponownym budowaniu celu. Ten cel jest uruchamiany po wstępnie zdefiniowanym celu CoreClean MSBuild.
Wykonaj ponowną kompilację rozwiązania programu Visual Studio i zobacz klienta wygenerowanego w folderze PetShopRestClient.

Teraz użyj wygenerowanego klienta. Przejdź do Program.csklienta i skopiuj następujący kod:

using System;
using System.Net.Http;

namespace PetReaderExecTaskExample
{
   internal class Program
   {
       private const string baseUrl = "https://petstore.swagger.io/v2";
       static void Main(string[] args)
       {
           HttpClient httpClient = new HttpClient();
           httpClient.BaseAddress = new Uri(baseUrl);
           var petClient = new PetShopRestClient.PetShopRestClient(httpClient);
           var pet = petClient.GetPetByIdAsync(1).Result;
           Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}");
       }
   }
}

Uwaga

Ten kod używa new HttpClient(), ponieważ jest prosty do zademonstrowania, ale nie jest to najlepsze rozwiązanie dla kodu w świecie rzeczywistym. Najlepszym rozwiązaniem jest użycie HttpClientFactory do utworzenia obiektu HttpClient, który rozwiązuje znane kwestie związane z żądaniem HttpClient, takie jak wyczerpanie zasobów lub problemy z nieaktualnym DNS. Zobacz Implementowanie odpornych żądań HTTPza pomocą interfejsu IHttpClientFactory.

Gratulacje! Teraz możesz wykonać program, aby zobaczyć, jak to działa.

Opcja 2. Niestandardowe zadanie pochodzące z narzędzia ToolTask

W wielu przypadkach użycie zadania Exec jest wystarczająco dobre, aby wykonać narzędzie zewnętrzne w celu wykonania czegoś takiego jak generowanie kodu klienta interfejsu API REST, ale co zrobić, jeśli chcesz zezwolić na generowanie kodu klienta interfejsu API REST, jeśli i tylko wtedy, gdy nie używasz bezwzględnej ścieżki systemu Windows jako danych wejściowych? A co zrobić, jeśli chcesz obliczyć w jakiś sposób, gdzie znajduje się plik wykonywalny? W sytuacji, gdy trzeba uruchomić kod w celu realizacji dodatkowych zadań, zadanie narzędzia MSBuild jest najlepszym rozwiązaniem. Klasa ToolTask jest abstrakcyjną klasą pochodzącą z TaskMSBuild. Można zdefiniować konkretną podklasę, która tworzy niestandardowe zadanie MSBuild. Takie podejście umożliwia uruchomienie dowolnego kodu potrzebnego do przygotowania do wykonania polecenia. Najpierw przeczytaj samouczek Tworzenie niestandardowego zadania na potrzeby generowania kodu.

Utworzysz zadanie niestandardowe pochodzące z MSBuild ToolTask, które wygeneruje klienta interfejsu API REST, ale zostanie zaprojektowane tak, aby emitować błąd, jeśli spróbujesz odwołać się do specyfikacji interfejsu OpenAPI przy użyciu adresu HTTP. NSwag obsługuje adres HTTP jako dane wejściowe specyfikacji interfejsu OpenAPI, ale na potrzeby tego przykładu załóżmy, że istnieje wymaganie projektowe, aby tego nie zezwalać.

Kompletny kod znajduje się w tym folderze PetReaderToolTaskExample; możesz pobrać i spojrzeć. W tym samouczku przejdziesz krok po kroku i poznasz pewne pojęcia, które można zastosować do własnych scenariuszy.

Utwórz nowy projekt programu Visual Studio dla zadania niestandardowego. Wywołaj go RestApiClientGenerator i użyj szablonu biblioteki klas (C#) przy użyciu platformy .NET Standard 2.0. Nadaj rozwiązaniu nazwę PetReaderToolTaskExample.
Usuń Class1.cs, który został wygenerowany automatycznie.

Dodaj pakiety NuGet Microsoft.Build.Utilities.Core:

Tworzenie klasy o nazwie RestApiClientGenerator

Odziedzicz po MSBuild ToolTask i zaimplementuj metodę abstrakcyjną, jak pokazano w poniższym kodzie:

using Microsoft.Build.Utilities;

namespace RestApiClientGenerator
{
    public class RestApiClientGenerator : ToolTask
    {
        protected override string ToolName => throw new System.NotImplementedException();

        protected override string GenerateFullPathToTool()
        {
            throw new System.NotImplementedException();
        }
    }
}

Dodaj następujące parametry:

InputOpenApiSpec, gdzie jest specyfikacja
ClientClassName, nazwa wygenerowanej klasy
ClientNamespaceName, przestrzeń nazw, w której jest generowana klasa
FolderClientClass, ścieżka do folderu, w którym będzie znajdować się klasa
NSwagCommandFullPath, pełna ścieżka do katalogu, w którym znajduje się NSwag.exe

     [Required]
     public string InputOpenApiSpec { get; set; }
     [Required]
     public string ClientClassName { get; set; }
     [Required]
     public string ClientNamespaceName { get; set; }
     [Required]
     public string FolderClientClass { get; set; }
     [Required]
     public string NSwagCommandFullPath { get; set; }

Zainstaluj narzędzie wiersza polecenia NSwag. Potrzebujesz pełnej ścieżki do katalogu, w którym znajduje się NSwag.exe.

Zaimplementuj metody abstrakcyjne:

   protected override string ToolName => "RestApiClientGenerator";

   protected override string GenerateFullPathToTool()
   {
       return $"{NSwagCommandFullPath}\\NSwag.exe";
   }

Istnieje wiele metod, które można zastąpić. Dla bieżącej implementacji zdefiniuj następujące dwa:

Zdefiniuj parametr polecenia:

  protected override string GenerateCommandLineCommands()
  {
      return $"openapi2csclient /input:{InputOpenApiSpec}  /classname:{ClientClassName} /namespace:{ClientNamespaceName} /output:{FolderClientClass}\\{ClientClassName}.cs";
  }

Walidacja parametru:

protected override bool ValidateParameters()
{
      //http address is not allowed
      var valid = true;
      if (InputOpenApiSpec.StartsWith("http:") || InputOpenApiSpec.StartsWith("https:"))
      {
          valid = false;
          Log.LogError("URL is not allowed");
      }

      return valid;
}

Uwaga

Tę prostą walidację można wykonać w inny sposób w pliku MSBuild, ale zaleca się wykonanie tej czynności w kodzie języka C# i hermetyzowanie polecenia i logiki.

Skompiluj projekt.

Tworzenie aplikacji konsolowej do korzystania z nowego zadania MSBuild

Następnym krokiem jest utworzenie aplikacji korzystającej z zadania.

Utwórz projekt Console App i nazwij go PetReaderToolTaskConsoleApp. Wybierz .NET 6.0 Oznacz go jako projekt startowy.
Utwórz projekt biblioteki klas w celu wygenerowania kodu o nazwie PetRestApiClient. Użyj platformy .NET Standard 2.1.
W projekcie PetReaderToolTaskConsoleApp utwórz zależność projektu do PetRestApiClient.
W projekcie PetRestApiClient utwórz folder PetRestApiClient. Ten folder będzie zawierać wygenerowany kod.
Usuń Class1.cs, który został wygenerowany automatycznie.
Na PetRestApiClientdodaj następujące pakiety NuGet:
- Plik Newtonsoft.Json potrzebny do skompilowania wygenerowanego klienta
- System.ComponentModel.Annotations— wymagane do skompilowania wygenerowanego klienta
W projekcie PetRestApiClient utwórz plik tekstowy o nazwie petshop-openapi-spec.json (w folderze projektu). Aby dodać specyfikację interfejsu OpenAPI, skopiuj zawartość z tutaj do pliku. Lubimy powtarzalną kompilację, która zależy tylko od danych wejściowych, jak wspomniano wcześniej. W tym przykładzie wystąpi błąd kompilacji, jeśli użytkownik wybierze adres URL jako dane wejściowe specyfikacji interfejsu OpenAPI.

Ważne

Ogólna ponowna budowa nie będzie działać. Zobaczysz błędy wskazujące, że nie można skopiować ani usunąć RestApiClientGenerator.dll". Jest to spowodowane tym, że próbuje skompilować zadanie niestandardowe MBuild w tym samym procesie kompilacji, który go używa. Wybierz PetReaderToolTaskConsoleApp i przebuduj tylko ten projekt. Inną możliwością jest umieszczenie niestandardowego zadania w całkowicie niezależnym rozwiązaniu Visual Studio, tak jak to jest w przykładzie w samouczku: Tworzenie niestandardowego zadania.

Skopiuj następujący kod do Program.cs:

 using System;
 using System.Net.Http;
 namespace PetReaderToolTaskConsoleApp
 {
   internal class Program
   {
       private const string baseUrl = "https://petstore.swagger.io/v2";
       static void Main(string[] args)
       {
           HttpClient httpClient = new HttpClient();
           httpClient.BaseAddress = new Uri(baseUrl);
           var petClient = new PetRestApiClient.PetRestApiClient(httpClient);
           var pet = petClient.GetPetByIdAsync(1).Result;
           Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}");
       }
   }
 }

Zmień instrukcje programu MSBuild, aby wywołać zadanie i wygenerować kod. Edytuj PetRestApiClient.csproj, wykonując następujące kroki:

Zarejestruj użycie niestandardowego zadania MSBuild:

XML

<UsingTask TaskName="RestApiClientGenerator.RestApiClientGenerator" AssemblyFile="..\RestApiClientGenerator\bin\Debug\netstandard2.0\RestApiClientGenerator.dll" />

Dodaj kilka właściwości potrzebnych do wykonania zadania:

XML

 <PropertyGroup>
    <!--The place where the OpenAPI spec is in-->
   <PetClientInputOpenApiSpec>petshop-openapi-spec.json</PetClientInputOpenApiSpec>
   <PetClientClientClassName>PetRestApiClient</PetClientClientClassName>
   <PetClientClientNamespaceName>PetRestApiClient</PetClientClientNamespaceName>
   <PetClientFolderClientClass>PetRestApiClient</PetClientFolderClientClass>
   <!--The directory where NSawg.exe is in-->
   <NSwagCommandFullPath>C:\Nsawg\Win</NSwagCommandFullPath>
  </PropertyGroup>

Ważne

Wybierz odpowiednią wartość NSwagCommandFullPath na podstawie lokalizacji instalacji w systemie.

Dodaj docelowy MSBuild, aby wygenerować klienta podczas procesu kompilacji. Ten element docelowy powinien zostać wykonany przed wykonaniem CoreCompile w celu wygenerowania kodu użytego w kompilacji.

XML

<Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetClientInputOpenApiSpec)" Outputs="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs">
  <!--Calling our custom task derivated from MSBuild Tool Task-->
  <RestApiClientGenerator InputOpenApiSpec="$(PetClientInputOpenApiSpec)" ClientClassName="$(PetClientClientClassName)" ClientNamespaceName="$(PetClientClientNamespaceName)" FolderClientClass="$(PetClientFolderClientClass)" NSwagCommandFullPath="$(NSwagCommandFullPath)"></RestApiClientGenerator>
</Target>

<Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean">
  <Delete Files="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs"></Delete>
</Target>

Input i Output są powiązane z kompilacji przyrostowej, a docelowy forceReGenerationOnRebuild usuwa wygenerowany plik po CoreClean, co wymusza ponowne wygenerowanie klienta podczas operacji ponownego kompilowania.

Wybierz PetReaderToolTaskConsoleApp i przebuduj tylko ten projekt. Teraz kod klienta jest generowany, a kod jest kompilowany. Można go wykonać i zobaczyć, jak działa. Ten kod generuje kod z pliku i jest dozwolony.
W tym kroku przedstawisz walidację parametru. W PetRestApiClient.csprojzmień właściwość $(PetClientInputOpenApiSpec), aby użyć adresu URL:

XML
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Wybierz PetReaderToolTaskConsoleApp i przebuduj tylko ten projekt. Zostanie wyświetlony błąd "Adres URL jest niedozwolony" zgodnie z wymaganiami projektowymi.

Pobieranie kodu

Zainstaluj narzędzie wiersza polecenia NSwag. Następnie będziesz potrzebować pełnej ścieżki do katalogu, w którym znajduje się NSwag.exe. Następnie zmodyfikuj PetRestApiClient.csproj i wybierz odpowiednią wartość $(NSwagCommandFullPath) na podstawie ścieżki instalacji na komputerze. Teraz wybierz pozycję RestApiClientGenerator i skompiluj tylko ten projekt, a następnie wybierz i ponownie skompiluj PetReaderToolTaskConsoleApp. Możesz wykonać PetReaderToolTaskConsoleApp. aby sprawdzić, czy wszystko działa zgodnie z oczekiwaniami.

Następne kroki

Możesz opublikować zadanie niestandardowe jako pakiet NuGet.

samouczek : tworzenie niestandardowego zadania

Możesz też dowiedzieć się, jak przetestować zadanie niestandardowe.

testowanie niestandardowego zadania MSBuild

Udostępnij za pośrednictwem