Wprowadzenie do sieciowych grup zabezpieczeń i platformy ASP.NET Core

Przez Christoph Nienaber, 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 użytkownika struktury Swagger i generatora struktury Swagger.
• Elastyczne możliwości generowania kodu.

W przypadku sieciowej grupy zabezpieczeń nie potrzebujesz istniejącego interfejsu API — możesz użyć interfejsów API innych firm, które zawierają program Swagger i generują 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ępniaj interfejs użytkownika struktury Swagger, aby przeglądać i testować internetowy interfejs API.
• Udostępniaj dokument Redoc, aby dodać dokumentację interfejsu 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 obsługi specyfikacji struktury Swagger, interfejsu użytkownika struktury Swagger (wersja 2 i wersja 3) oraz interfejsu użytkownika redoc. NSwag 14 obsługuje tylko 3 specyfikacji interfejsu użytkownika struktury Swagger.

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

Program Visual Studio

• W oknie konsoli Menedżer pakietów:

  • Przejdź do pozycji Wyświetl>inne okna> Menedżer pakietów Konsola

  • Przejdź do katalogu, w którym NSwagSample.csproj istnieje plik

  • Wykonaj następujące polecenie:

    Install-Package NSwag.AspNetCore
    

• W oknie dialogowym Zarządzanie pakietami NuGet:

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań> Zarządzanie pakietami NuGet
  • Ustaw źródło pakietu na wartość "nuget.org"
  • Wprowadź ciąg "NSwag.AspNetCore" w polu wyszukiwania
  • Wybierz pakiet "NSwag.AspNetCore" na karcie Przeglądaj , a następnie kliknij przycisk Zainstaluj

Visual Studio dla komputerów Mac

• Kliknij prawym przyciskiem myszy folder Packages w okienku >rozwiązania Dodaj pakiety...
• Ustaw listę rozwijaną Źródło w oknie Dodawanie pakietów na "nuget.org"
• Wprowadź ciąg "NSwag.AspNetCore" w polu wyszukiwania
• Wybierz pakiet "NSwag.AspNetCore" w okienku wyników i kliknij pozycję Dodaj pakiet

Visual Studio Code

Uruchom następujące polecenie w zintegrowanym terminalu:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Interfejs wiersza polecenia platformy .NET

Uruchom następujące polecenie:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Dodawanie i konfigurowanie oprogramowania pośredniczącego struktury 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 obsługi wygenerowanej specyfikacji openApi, interfejsu użytkownika struktury Swagger i interfejsu użytkownika narzędzia Redoc również w systemie 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:
  • http://localhost:<port>/swagger aby wyświetlić interfejs użytkownika struktury Swagger.
  • http://localhost:<port>/swagger/v1/swagger.json aby wyświetlić specyfikację struktury Swagger.

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.
• Połączona usługa OpenAPI (Swagger): połączona usługa programu Visual Studio służąca do generowania kodu klienta interfejsu API w języku C# lub TypeScript. Generuje również kontrolery języka C# dla usług OpenAPI za pomocą sieciowej grupy zabezpieczeń.

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ę narzędzia xcopy, która może zostać uruchomiona bez uprawnień administratora i instalacji.
• Uruchom aplikację swagger.json NSwagStudio i wprowadź adres URL pliku w polu tekstowym Adres URL specyfikacji struktury Swagger. Na przykład http://localhost:5232/swagger/v1/swagger.json.
• Kliknij przycisk Utwórz lokalną kopię , aby wygenerować reprezentację formatu JSON specyfikacji struktury Swagger.

• W obszarze Dane wyjściowe kliknij pole wyboru Klient CSharp. W zależności od projektu możesz również wybrać klienta TypeScript lub kontrolera internetowego interfejsu API CSharp. W przypadku wybrania kontrolera internetowego interfejsu API CSharp specyfikacja usługi ponownie kompiluje usługę, służąc jako generowanie odwrotne.
• 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:

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

Napiwek

Kod klienta języka C# jest generowany na podstawie wyborów na karcie Ustawienia . Zmodyfikuj ustawienia, aby wykonywać zadania, takie jak domyślna przestrzeń nazw i synchroniczna generacja metody.

• 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

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

Informacje i opis interfejsu API

W Program.csprogramie zaktualizuj informacje AddOpenApiDocument o dokumencie internetowego interfejsu API i dołącz więcej informacji, takich jak autor, licencja i opis. Najpierw zaimportuj NSwag OpenApi przestrzeń nazw, aby używać klas.

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

W interfejsie użytkownika struktury Swagger są wyświetlane informacje o wersji:

Komentarze XML

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

Program Visual Studio

• Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Edit <project_name>.csproj.
• Ręcznie dodaj wyróżnione wiersze do .csproj pliku:

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

Visual Studio dla komputerów Mac

• W okienku rozwiązania naciśnij kontrolkę i kliknij nazwę projektu. Przejdź do pozycji Narzędzia>Edytuj plik.
• Ręcznie dodaj wyróżnione wiersze do .csproj pliku:

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

Visual Studio Code

Ręcznie dodaj wyróżnione wiersze do .csproj pliku:

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

Interfejs wiersza polecenia platformy .NET

Ręcznie dodaj wyróżnione wiersze do .csproj pliku:

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

Włączenie komentarzy XML zapewnia informacje debugowania dla nieudokumentowanych typów publicznych i elementów członkowskich. Nieudokumentowane typy i elementy członkowskie są wskazywane przez komunikat ostrzegawczy. 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łączanie kodów ostrzegawczych w celu $(NoWarn); zastosowania wartości domyślnych języka C#.

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

Aby pominąć ostrzeżenia tylko dla określonych elementów członkowskich, należy ująć kod w #pragma dyrektywy preprocesora ostrzegawczego . 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. Wymuszanie kodu ostrzegawczego jest przywracane na zamknięciu 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 do danych

Oznacz model atrybutami znajdującymi się w przestrzeni nazw, aby pomóc w kierowania składnikami interfejsu System.ComponentModel.DataAnnotations użytkownika struktury Swagger.

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

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ę wzrostu użycia adnotacji danych w internetowym interfejsie API strony pomocy interfejsu użytkownika i interfejsu API stają się bardziej opisowe i przydatne.

Opisywanie typów odpowiedzi

Deweloperzy korzystający z internetowego interfejsu API są najbardziej zainteresowani zwracanymi typami odpowiedzi i kodami błędów (jeśli nie są standardami). 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 interfejsie użytkownika struktury Swagger użytkownik nie zna tych oczekiwanych wyników. 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ą służyć jako alternatywa do jawnego dekorowania poszczególnych akcji za pomocą polecenia [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Używanie konwencji internetowego interfejsu API.

Ponowne dokumenty

Redoc to alternatywa dla interfejsu użytkownika struktury Swagger. Jest ona podobna, ponieważ udostępnia również stronę dokumentacji internetowego interfejsu API przy użyciu specyfikacji interfejsu 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ć dokument Redoc, dodaj oprogramowanie pośredniczące 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 witryny , aby wyświetlić interfejs użytkownika narzędzia Redoc: