Wprowadzenie do NSwag i platformy ASP.NET Core

Autor : Rico Suter i Dave Brock

Wyświetl lub pobierz przykładowy kod (jak pobrać)

NSwag oferuje następujące możliwości:

• Możliwość korzystania z interfejsu Swagger UI i generatora Swaggera.
• Elastyczne możliwości generowania kodu.

Dzięki NSwag nie potrzebujesz istniejącego interfejsu API — możesz używać interfejsów API innych firm, które korzystają ze Swaggera, i wygenerować implementację klienta. NSwag pozwala przyspieszyć cykl programowania i łatwo dostosować się do zmian interfejsu API.

Instalacja pakietu

Zainstaluj serwer NSwag, aby:

• Wygeneruj specyfikację struktury Swagger dla zaimplementowanego internetowego interfejsu API.
• Udostępnianie interfejsu Swagger UI do przeglądania i testowania internetowego interfejsu API.
• Hostuj Redoc, aby dodać dokumentację API dla internetowego interfejsu API.

Aby użyć oprogramowania pośredniczącego NSwag ASP.NET Core, zainstaluj pakiet NuGet NSwag.AspNetCore. Ten pakiet zawiera oprogramowanie pośredniczące do generowania i udostępniania specyfikacji Swagger, interfejsu użytkownika Swagger (v2 i v3) oraz ReDoc UI. NSwag 14 obsługuje tylko wersję 3 specyfikacji Swagger UI.

Aby zainstalować pakiet NuGet NSwag, użyj jednej z następujących metod:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Dodaj i skonfiguruj oprogramowanie pośrednie Swagger

Dodaj i skonfiguruj program Swagger w aplikacji ASP.NET Core, wykonując następujące kroki:

• Dodaj generator OpenApi do kolekcji usług w pliku Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();

• Włącz oprogramowanie pośredniczące do udostępniania wygenerowanej specyfikacji OpenAPI, interfejsu Swagger UI oraz interfejsu Redoc UI, również w Program.cs:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

• Uruchomić aplikację. Przejdź do:
  • Kliknij http://localhost:<port>/swagger, aby wyświetlić interfejs użytkownika Swagger.
  • http://localhost:<port>/swagger/v1/swagger.json aby wyświetlić specyfikację Swaggera.

Generowanie kodu

Możesz skorzystać z możliwości generowania kodu NSwag, wybierając jedną z następujących opcji:

• NSwagStudio: aplikacja klasyczna systemu Windows do generowania kodu klienta interfejsu API w języku C# lub TypeScript.
• Pakiety NuGet NSwag.CodeGeneration.CSharp lub NSwag.CodeGeneration.TypeScript na potrzeby generowania kodu wewnątrz projektu.
• NSwag z wiersza polecenia.
• Pakiet NuGet NSwag.MSBuild.
• Unchase OpenAPI (Swagger) Connected Service: usługa połączona programu Visual Studio służąca do generowania kodu klienta API w języku C# lub TypeScript. Generuje również kontrolery w języku C# dla usług OpenAPI za pomocą narzędzia NSwag.

Generowanie kodu za pomocą aplikacji NSwagStudio

• Zainstaluj aplikację NSwagStudio, postępując zgodnie z instrukcjami w repozytorium GitHub NSwagStudio. Na stronie wydań NSwag można pobrać wersję xcopy, którą można uruchomić bez instalacji i uprawnień administratora.
• Uruchom program NSwagStudio i wprowadź adres URL pliku swagger.json w polu tekstowym Adres URL specyfikacji Swagger. Na przykład http://localhost:5232/swagger/v1/swagger.json.
• Wybierz przycisk Utwórz lokalną kopię , aby wygenerować reprezentację formatu JSON specyfikacji struktury Swagger.

• W obszarze Dane wyjściowe zaznacz pole wyboru Klient CSharp . W zależności od projektu możesz również wybrać klienta TypeScript lub kontrolera internetowego interfejsu API CSharp. Jeśli wybierzesz kontroler internetowego interfejsu API CSharp, specyfikacja usługi odtworzy usługę, działając jako odwrotne generowanie.
• Wybierz pozycję Generuj dane wyjściowe , aby utworzyć kompletną implementację klienta języka C# projektu TodoApi.NSwag . Aby wyświetlić wygenerowany kod klienta, wybierz kartę Klient CSharp :

namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // code omitted for brevity

• Skopiuj wygenerowany kod języka C# do pliku w projekcie klienta, który będzie używać interfejsu API.
• Rozpocznij korzystanie z internetowego interfejsu API:

var todoClient = new TodoClient(new HttpClient());

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

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

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

Dostosowywanie dokumentacji interfejsu API

OpenApi zapewnia możliwości dokumentowania modelu obiektów, aby ułatwić korzystanie z internetowego interfejsu API.

Informacje i opis interfejsu API

W Program.cs zaktualizuj AddOpenApiDocument, aby skonfigurować informacje o dokumencie interfejsu Web API i uwzględnić dodatkowe informacje, takie jak autor, licencja i opis. Najpierw zaimportuj przestrzeń nazw NSwag, aby używać klas OpenApi.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApiDocument(options => {
     options.PostProcess = document =>
     {
         document.Info = new OpenApiInfo
         {
             Version = "v1",
             Title = "ToDo API",
             Description = "An ASP.NET Core Web API for managing ToDo items",
             TermsOfService = "https://example.com/terms",
             Contact = new OpenApiContact
             {
                 Name = "Example Contact",
                 Url = "https://example.com/contact"
             },
             License = new OpenApiLicense
             {
                 Name = "Example License",
                 Url = "https://example.com/license"
             }
         };
     };
});

Swagger UI wyświetla informacje o wersji:

Komentarze XML

Aby włączyć komentarze XML, wykonaj następujące kroki:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Włączenie komentarzy XML udostępnia informacje debugowania dotyczące nieudokumentowanych typów publicznych i ich składników. Nieudokumentowane typy i składowe są oznaczane komunikatem ostrzegawczym. Na przykład następujący komunikat wskazuje naruszenie kodu ostrzeżenia 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoContext'

Aby pominąć ostrzeżenia dla całego projektu, zdefiniuj rozdzielaną średnikami listę kodów ostrzeżeń, które mają być ignorowane w pliku projektu. Dołączenie kodów ostrzegawczych do $(NoWarn); powoduje również zastosowanie domyślnych wartości języka C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Aby wyłączyć ostrzeżenia tylko dla określonych składowych, należy otoczyć kod dyrektywami preprocesora #pragma warning. Takie podejście jest przydatne w przypadku kodu, który nie powinien być udostępniany za pośrednictwem dokumentacji interfejsu API. W poniższym przykładzie kod ostrzeżenia CS1591 jest ignorowany dla całej TodoContext klasy. Stosowanie kodu ostrzeżenia zostaje przywrócone po zakończeniu definicji klasy. Określ wiele kodów ostrzegawczych z rozdzielaną przecinkami listą.

namespace NSwagSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Adnotacje danych

Oznacz model atrybutami znajdującymi się w przestrzeni nazw System.ComponentModel.DataAnnotations, aby sterować składnikami interfejsu użytkownika Swagger UI.

Dodaj atrybut [Required] do właściwości Name klasy TodoItem:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace NSwagSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Obecność tego atrybutu zmienia zachowanie interfejsu użytkownika i zmienia bazowy schemat JSON:

"TodoItem": {
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "isComplete": {
      "type": "boolean",
      "default": false
    }
  }
}

W miarę coraz szerszego wykorzystania adnotacji danych w internetowym interfejsie API strony pomocy dla interfejsu użytkownika i interfejsu API stają się bardziej szczegółowe i przydatne.

Opisywanie typów odpowiedzi

Deweloperów korzystających z webowego interfejsu API najbardziej interesuje to, co jest zwracane — konkretnie typy odpowiedzi i kody błędów (jeśli nie są standardowe). Typy odpowiedzi i kody błędów są oznaczone w komentarzach XML i adnotacjach danych.

Akcja Create zwraca kod stanu HTTP 201 w przypadku powodzenia. Kod stanu HTTP 400 jest zwracany, gdy wysłana treść żądania to null. Bez odpowiedniej dokumentacji w Swagger UI konsument nie ma wiedzy o tych oczekiwanych rezultatach. Rozwiąż ten problem, dodając wyróżnione wiersze w poniższym przykładzie:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Interfejs użytkownika struktury Swagger teraz wyraźnie dokumentuje oczekiwane kody odpowiedzi HTTP (a komentarze XML są również wyświetlane):

Konwencje mogą stanowić alternatywę dla jawnego oznaczania poszczególnych akcji za pomocą elementu [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Korzystanie z konwencji interfejsu API sieci Web.

Redoc

Redoc to alternatywa dla Swagger UI. Jest podobna, ponieważ również udostępnia stronę z dokumentacją interfejsu Web API z użyciem specyfikacji OpenAPI. Różnica polega na tym, że interfejs użytkownika redoc jest bardziej skoncentrowany na dokumentacji i nie zapewnia interaktywnego interfejsu użytkownika do testowania interfejsu API.

Aby włączyć Redoc, dodaj jego middleware do Program.cs:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI is called only in Development.
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Uruchom aplikację i przejdź do http://localhost:<port>/redoc, aby wyświetlić interfejs Redoc:

Autor : Rico Suter i Dave Brock

Wyświetl lub pobierz przykładowy kod (jak pobrać)

NSwag oferuje następujące możliwości:

• Możliwość korzystania z interfejsu Swagger UI i generatora Swaggera.
• Elastyczne możliwości generowania kodu.

Dzięki NSwag nie potrzebujesz istniejącego interfejsu API — możesz używać interfejsów API innych firm, które korzystają ze Swaggera, i wygenerować implementację klienta. NSwag pozwala przyspieszyć cykl programowania i łatwo dostosować się do zmian interfejsu API.

Rejestrowanie oprogramowania pośredniczącego NSwag

Zarejestruj oprogramowanie pośredniczące NSwag, aby:

• Wygeneruj specyfikację struktury Swagger dla zaimplementowanego internetowego interfejsu API.
• Udostępnianie interfejsu Swagger UI do przeglądania i testowania internetowego interfejsu API.

Aby użyć oprogramowania pośredniczącego NSwag ASP.NET Core, zainstaluj pakiet NuGet NSwag.AspNetCore. Ten pakiet zawiera oprogramowanie pośredniczące do generowania i udostępniania specyfikacji Swagger, interfejsu użytkownika Swagger (v2 i v3) oraz ReDoc UI.

Aby zainstalować pakiet NuGet NSwag, użyj jednej z następujących metod:

dotnet add TodoApi.csproj package NSwag.AspNetCore

dotnet add TodoApi.csproj package NSwag.AspNetCore

Dodaj i skonfiguruj oprogramowanie pośrednie Swagger

Dodaj i skonfiguruj program Swagger w aplikacji ASP.NET Core, wykonując następujące kroki:

• W metodzie Startup.ConfigureServices zarejestruj wymagane usługi Swagger:

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 middleware obsługujące wygenerowaną specyfikację Swaggera oraz interfejs użytkownika Swagger UI:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseOpenApi();
    if (env.IsDevelopment())
    {
        app.UseSwaggerUi3();
    }
    app.UseMvc();
}

• Uruchomić aplikację. Przejdź do:
  • Kliknij http://localhost:<port>/swagger, aby wyświetlić interfejs użytkownika Swagger.
  • http://localhost:<port>/swagger/v1/swagger.json aby wyświetlić specyfikację Swaggera.

Generowanie kodu

Możesz skorzystać z możliwości generowania kodu NSwag, wybierając jedną z następujących opcji:

• NSwagStudio: aplikacja klasyczna systemu Windows do generowania kodu klienta interfejsu API w języku C# lub TypeScript.
• Pakiety NuGet NSwag.CodeGeneration.CSharp lub NSwag.CodeGeneration.TypeScript na potrzeby generowania kodu wewnątrz projektu.
• NSwag z wiersza polecenia.
• Pakiet NuGet NSwag.MSBuild.
• Unchase OpenAPI (Swagger) Connected Service: usługa połączona programu Visual Studio służąca do generowania kodu klienta API w języku C# lub TypeScript. Generuje również kontrolery w języku C# dla usług OpenAPI za pomocą narzędzia NSwag.

Generowanie kodu za pomocą aplikacji NSwagStudio

• Zainstaluj aplikację NSwagStudio, postępując zgodnie z instrukcjami w repozytorium GitHub NSwagStudio. Na stronie wydania NSwag można pobrać wersję xcopy, która może zostać uruchomiona bez uprawnień instalacji i administratora.

• Uruchom program NSwagStudio i wprowadź adres URL pliku swagger.json w polu tekstowym Adres URL specyfikacji Swagger. Na przykład http://localhost:44354/swagger/v1/swagger.json.

• Kliknij przycisk Utwórz kopię lokalną, aby wygenerować reprezentację JSON specyfikacji Swaggera.

  

• W obszarze Dane wyjściowe kliknij pole wyboru CSharp Client. W zależności od projektu możesz również wybrać klienta TypeScript lub kontrolera internetowego interfejsu API CSharp. Jeśli wybierzesz kontroler internetowego interfejsu API CSharp, specyfikacja usługi odtworzy usługę, działając jako odwrotne generowanie.

• Kliknij pozycję Generuj dane wyjściowe , aby utworzyć kompletną implementację klienta języka C# projektu TodoApi.NSwag . Aby wyświetlić wygenerowany kod klienta, kliknij kartę Klient CSharp:

//----------------------
// <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

• Skopiuj wygenerowany kod języka C# do pliku w projekcie klienta, który będzie używać interfejsu API.
• Rozpocznij korzystanie z internetowego interfejsu 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);

Dostosowywanie dokumentacji interfejsu API

Program Swagger udostępnia opcje dokumentowania modelu obiektów w celu ułatwienia użycia internetowego interfejsu API.

Informacje i opis interfejsu API

W metodzie Startup.ConfigureServices akcja konfiguracji przekazana do AddSwaggerDocument metody dodaje informacje, takie jak autor, licencja i opis:

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"
        };
    };
});

Swagger UI wyświetla informacje o wersji:

Komentarze XML

Aby włączyć komentarze XML, wykonaj następujące kroki:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Adnotacje danych

Ponieważ NSwag używa mechanizmu refleksji, a zalecanym typem zwracanym dla akcji internetowego API jest ActionResult<T>, może jedynie wywnioskować typ zwracany zdefiniowany przez T. Nie można automatycznie wywnioskować innych możliwych typów zwracanych.

Rozważmy następujący przykład:

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

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

Poprzednia akcja zwraca wartość ActionResult<T>. Wewnątrz akcji zwracane jest CreatedAtRoute. Ponieważ kontroler ma [ApiController] atrybut, BadRequest odpowiedź jest również możliwa. Aby uzyskać więcej informacji, zobacz Automatyczne odpowiedzi HTTP 400. Użyj atrybutów adnotacji danych, aby wskazać klientom, jakie kody stanu HTTP może zwracać ta akcja. Oznacz akcję następującymi atrybutami:

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

W ASP.NET Core 2.2 lub nowszym można użyć konwencji zamiast jawnego dekorowania poszczególnych akcji za pomocą polecenia [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Korzystanie z konwencji interfejsu API sieci Web.

Generator Swagger może teraz dokładnie opisać tę akcję, a wygenerowani klienci wiedzą, co otrzymają podczas wywoływania punktu końcowego. Jako zalecenie oznacz wszystkie akcje za pomocą tych atrybutów.

Aby uzyskać wskazówki dotyczące odpowiedzi HTTP, które powinny zwracać akcje interfejsu API, zobacz RFC 9110: Semantyka HTTP (sekcja 9.3). Definicje metod).