Wprowadzenie do NSwag i ASP.NET CoreGet started with NSwag and ASP.NET Core

Christoph Nienaber, Suteri Dave BrockBy Christoph Nienaber, Rico Suter, and Dave Brock

NSwag oferuje następujące możliwości:NSwag offers the following capabilities:

  • Możliwość korzystania z interfejsu użytkownika programu Swagger i generatora Swagger.The ability to utilize the Swagger UI and Swagger generator.
  • Elastyczne możliwości generowania kodu.Flexible code generation capabilities.

W przypadku usługi NSwag nie jest potrzebny istniejący interfejs API—można używać interfejsów API innych firm, które zawierają strukturę Swagger i generować implementację klienta.With NSwag, you don't need an existing API—you can use third-party APIs that incorporate Swagger and generate a client implementation. NSwag umożliwia przyspieszenie cyklu programowania i łatwe dostosowanie do zmian interfejsu API.NSwag allows you to expedite the development cycle and easily adapt to API changes.

Rejestrowanie oprogramowania pośredniczącego NSwagRegister the NSwag middleware

Zarejestruj oprogramowanie pośredniczące NSwag w programie:Register the NSwag middleware to:

  • Generuj specyfikację Swagger dla zaimplementowanego interfejsu API sieci Web.Generate the Swagger specification for the implemented web API.
  • Zaoferują interfejs użytkownika struktury Swagger, aby przeglądać i testować internetowy interfejs API.Serve the Swagger UI to browse and test the web API.

Aby użyć oprogramowania NSwag ASP.NET Core pośredniczącego, zainstaluj pakiet NuGet NSwag. AspNetCore .To use the NSwag ASP.NET Core middleware, install the NSwag.AspNetCore NuGet package. Ten pakiet zawiera oprogramowanie pośredniczące do generowania i obsługiwania specyfikacji struktury Swagger, interfejsu użytkownika struktury Swagger (v2 i V3) oraz interfejsu użytkownika ReDoc.This package contains the middleware to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.

Aby zainstalować pakiet NuGet NSwag, należy użyć jednej z następujących metod:Use one of the following approaches to install the NSwag NuGet package:

  • W oknie konsola Menedżera pakietów :From the Package Manager Console window:

    • Przejdź do widoku > innej konsoli Menedżera pakietów > WindowsGo to View > Other Windows > Package Manager Console

    • Przejdź do katalogu, w którym znajduje się plik TodoApi. csprojNavigate to the directory in which the TodoApi.csproj file exists

    • Wykonaj następujące polecenie:Execute the following command:

      Install-Package NSwag.AspNetCore
      
  • W oknie dialogowym Zarządzanie pakietami NuGet :From the Manage NuGet Packages dialog:

    • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań > Zarządzanie pakietami NuGetRight-click the project in Solution Explorer > Manage NuGet Packages
    • Ustaw Źródło pakietu na "NuGet.org"Set the Package source to "nuget.org"
    • Wprowadź ciąg "NSwag. AspNetCore" w polu wyszukiwaniaEnter "NSwag.AspNetCore" in the search box
    • Wybierz pakiet "NSwag. AspNetCore" z karty Przeglądaj , a następnie kliknij przycisk Instaluj .Select the "NSwag.AspNetCore" package from the Browse tab and click Install

Dodawanie i Konfigurowanie oprogramowania pośredniczącego programu SwaggerAdd and configure Swagger middleware

Dodaj i skonfiguruj strukturę Swagger w aplikacji ASP.NET Core, wykonując następujące czynności:Add and configure Swagger in your ASP.NET Core app by performing the following steps:

  • W metodzie Startup.ConfigureServices Zarejestruj wymagane usługi Swagger:In the Startup.ConfigureServices method, register the required Swagger services:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • W metodzie Startup.Configure Włącz oprogramowanie pośredniczące do obsługi wygenerowanej specyfikacji struktury Swagger i interfejsu użytkownika programu Swagger:In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and the Swagger UI:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}
  • Uruchomić aplikację.Launch the app. Przejdź do:Navigate to:
    • http://localhost:<port>/swagger wyświetlić interfejsu użytkownika struktury Swagger.http://localhost:<port>/swagger to view the Swagger UI.
    • http://localhost:<port>/swagger/v1/swagger.json wyświetlić specyfikacji struktury Swagger.http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

Generowanie koduCode generation

Aby skorzystać z możliwości generowania kodu w programie NSwag, należy wybrać jedną z następujących opcji:You can take advantage of NSwag's code generation capabilities by choosing one of the following options:

Generuj kod przy użyciu NSwagStudioGenerate code with NSwagStudio

  • Zainstaluj program NSwagStudio, postępując zgodnie z instrukcjami w repozytorium GitHub NSwagStudio.Install NSwagStudio by following the instructions at the NSwagStudio GitHub repository. Na stronie wydanie NSwag można pobrać wersję narzędzia XCOPY, którą można uruchomić bez uprawnień instalacji i administratora.On the NSwag release page you can download an xcopy version which can be started without installation and admin privileges.

  • Uruchom NSwagStudio i wprowadź adres URL pliku Swagger. JSON w polu tekstowym adres URL specyfikacji struktury Swagger .Launch NSwagStudio and enter the swagger.json file URL in the Swagger Specification URL text box. Przykładowy adres URL to http://localhost:44354/swagger/v1/swagger.json .For example, http://localhost:44354/swagger/v1/swagger.json.

  • Kliknij przycisk Utwórz kopię lokalną , aby wygenerować reprezentację JSON specyfikacji struktury Swagger.Click the Create local Copy button to generate a JSON representation of your Swagger specification.

    Utwórz lokalną kopię specyfikacji struktury Swagger

  • W obszarze dane wyjściowe kliknij pole wyboru Klient CSharp .In the Outputs area, click the CSharp Client check box. W zależności od projektu można również wybrać klienta TypeScript lub kontroler internetowego interfejsu API CSharp.Depending on your project, you can also choose TypeScript Client or CSharp Web API Controller. W przypadku wybrania opcji kontroler internetowego interfejsu API CSharpSpecyfikacja usługi ponownie kompiluje usługę, służącą jako generacja odwrotna.If you select CSharp Web API Controller, a service specification rebuilds the service, serving as a reverse generation.

  • Kliknij pozycję Generuj dane wyjściowe , aby C# utworzyć kompletną implementację projektu TodoApi. NSwag .Click Generate Outputs to produce a complete C# client implementation of the TodoApi.NSwag project. Aby wyświetlić wygenerowany kod klienta, kliknij kartę Klient CSharp :To see the generated client code, click the CSharp Client tab:

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

Porada

Kod C# klienta jest generowany na podstawie opcji wybranych na karcie Ustawienia . zmodyfikuj ustawienia, aby wykonać zadania, takie jak domyślna zmiana nazw obszaru nazw i generowanie metody synchronicznej.The C# client code is generated based on selections in the Settings tab. Modify the settings to perform tasks such as default namespace renaming and synchronous method generation.

  • Skopiuj wygenerowany C# kod do pliku w projekcie klienta, który będzie korzystał z interfejsu API.Copy the generated C# code into a file in the client project that will consume the API.
  • Rozpocznij korzystanie z internetowego interfejsu API:Start consuming the web API:
 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Dostosuj dokumentację interfejsu APICustomize API documentation

Struktura Swagger zawiera opcje dokumentujące model obiektów, co ułatwia użycie internetowego interfejsu API.Swagger provides options for documenting the object model to ease consumption of the web API.

Informacje o interfejsie API i opisAPI info and description

W metodzie Startup.ConfigureServices akcja konfiguracyjna przeniesiona do metody AddSwaggerDocument dodaje takie informacje, jak autor, licencja i opis:In the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds information such as the author, license, and description:

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Interfejs użytkownika struktury Swagger wyświetla informacje o wersji:The Swagger UI displays the version's information:

Interfejs użytkownika struktury Swagger z informacjami o wersji

komentarze XMLXML comments

Aby włączyć Komentarze XML, wykonaj następujące czynności:To enable XML comments, perform the following steps:

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań a następnie wybierz polecenie edytuj < Project_Name >. csproj.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • Ręcznie Dodaj wyróżnione wiersze do pliku csproj :Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz polecenie WłaściwościRight-click the project in Solution Explorer and select Properties
  • Sprawdź pole plik dokumentacji XML w sekcji dane wyjściowe na karcie kompilacjaCheck the XML documentation file box under the Output section of the Build tab

Adnotacje danychData annotations

Ponieważ NSwag używa odbicia, a zalecanym typem zwracanym dla akcji interfejsu API sieci Web jest IActionResult, nie może wnioskować o to, co działa i co zwraca.Because NSwag uses Reflection, and the recommended return type for web API actions is IActionResult, it can't infer what your action is doing and what it returns.

Rozważmy następujący przykład:Consider the following example:

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Poprzednia akcja zwraca IActionResult, ale wewnątrz akcji, zwraca albo CreatedAtRoute lub nieprawidłowego żądania.The preceding action returns IActionResult, but inside the action it's returning either CreatedAtRoute or BadRequest. Użyj adnotacji danych, aby poinformować klientów, których kodów stanu HTTP Ta akcja jest zwracana.Use data annotations to tell clients which HTTP status codes this action is known to return. Oznacz akcję następującymi atrybutami:Mark the action with the following attributes:

[ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]  // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]                 // BadRequest

Ponieważ NSwag używa odbicia, a zalecanym typem zwracanym dla akcji interfejsu API sieci Web jest ActionResult<t >, może on tylko wnioskować o typie zwracanym zdefiniowanym przez T.Because NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>, it can only infer the return type defined by T. Nie można automatycznie wywnioskować innych możliwych typów zwracanych.You can't automatically infer other possible return types.

Rozważmy następujący przykład:Consider the following example:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Poprzednia akcja zwraca ActionResult<T>.The preceding action returns ActionResult<T>. Wewnątrz akcji zwraca CreatedAtRoute.Inside the action, it's returning CreatedAtRoute. Ponieważ kontroler ma atrybut [ApiController] , istnieje również odpowiedź nieprawidłowego żądania .Since the controller has the [ApiController] attribute, a BadRequest response is possible, too. Aby uzyskać więcej informacji, zobacz Automatyczne HTTP 400 odpowiedzi.For more information, see Automatic HTTP 400 responses. Użyj adnotacji danych, aby poinformować klientów, których kodów stanu HTTP Ta akcja jest zwracana.Use data annotations to tell clients which HTTP status codes this action is known to return. Oznacz akcję następującymi atrybutami:Mark the action with the following attributes:

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

W ASP.NET Core 2,2 lub nowszych można używać konwencji zamiast jawnie dekorowania nazwy poszczególnych akcji z [ProducesResponseType].In ASP.NET Core 2.2 or later, you can use conventions instead of explicitly decorating individual actions with [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz temat Korzystanie z Konwencji interfejsu API sieci Web.For more information, see Korzystanie z Konwencji interfejsu API sieci Web.

Generator Swagger może teraz prawidłowo opisać tę akcję, a wygenerowane klienci wiedzą, co otrzymują podczas wywoływania punktu końcowego.The Swagger generator can now accurately describe this action, and generated clients know what they receive when calling the endpoint. Zgodnie z zaleceniem Oznacz wszystkie akcje z tymi atrybutami.As a recommendation, mark all actions with these attributes.

Aby uzyskać wskazówki dotyczące odpowiedzi HTTP, które powinny być zwracane przez działania interfejsu API, zobacz specyfikację RFC 7231.For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.