Wprowadzenie do pakietu Swashbuckle i platformy ASP.NET Core

Uwaga

Pakiet Swashbuckle nie jest dostępny na platformie .NET 9 i nowszych wersjach. Aby uzyskać inną opcję, zobacz Omówienie obsługi OpenAPI w aplikacjach ASP.NET Core API.

Pakiet Swashbuckle składa się z trzech głównych składników:

• Swashbuckle.AspNetCore.Swagger: model obiektów i oprogramowanie pośredniczące Swagger do uwidaczniania obiektów SwaggerDocument jako punktów końcowych JSON.

• Swashbuckle.AspNetCore.SwaggerGen: generator Swagger, który tworzy SwaggerDocument obiekty bezpośrednio na podstawie tras, kontrolerów i modeli. Zazwyczaj jest ona łączona z oprogramowaniem pośredniczącym dla punktu końcowego Swagger, aby automatycznie uwidaczniać Swagger JSON.

• Swashbuckle.AspNetCore.SwaggerUI: osadzona wersja narzędzia Swagger UI. Interpretuje plik JSON programu Swagger w celu tworzenia bogatego, konfigurowalnego doświadczenia do opisywania funkcjonalności internetowego API. Obejmuje wbudowane ramy testowe dla metod publicznych.

Instalacja pakietu

Swashbuckle można dodać przy użyciu następujących sposobów:

Visual Studio

• W oknie Menedżera pakietów konsoli:

  • Przejdź do Wyświetl>Inne okna>Konsola Menedżera pakietów

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

  • Wykonaj następujące polecenie:

    Install-Package Swashbuckle.AspNetCore -Version 6.6.2
    

• 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"
  • Upewnij się, że opcja "Uwzględnij wersję wstępną" jest włączona
  • Wprowadź ciąg "Swashbuckle.AspNetCore" w polu wyszukiwania
  • Wybierz najnowszy pakiet "Swashbuckle.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 Solution Pad>Dodaj pakiety...
• Ustaw listę rozwijaną Źródło w oknie Dodawanie pakietów na "nuget.org"
• Upewnij się, że opcja "Pokaż pakiety wersji wstępnej" jest włączona
• Wprowadź ciąg "Swashbuckle.AspNetCore" w polu wyszukiwania
• Wybierz najnowszy pakiet "Swashbuckle.AspNetCore" w okienku wyników i kliknij pozycję Dodaj pakiet

Visual Studio Code

Uruchom następujące polecenie w zintegrowanym terminalu:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

.NET CLI

Uruchom następujące polecenie:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

Dodawanie i konfigurowanie middleware Swagger

Dodaj generator Swagger do kolekcji usług w Program.cs:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Wywołanie AddEndpointsApiExplorer, pokazane w poprzednim przykładzie, jest wymagane tylko dla minimalnych API. Aby uzyskać więcej informacji, zobacz ten wpis StackOverflow.

Włącz oprogramowanie pośredniczące do obsługi wygenerowanego dokumentu JSON i interfejsu użytkownika programu Swagger, również w pliku Program.cs:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Powyższy kod dodaje middleware Swagger tylko wtedy, gdy bieżące środowisko jest ustawione na Deweloperskie. Wywołanie UseSwaggerUI metody umożliwia osadzoną wersję narzędzia Swagger UI.

Uruchom aplikację i przejdź do https://localhost:<port>/swagger/v1/swagger.jsonadresu . Wygenerowany dokument opisujący punkty końcowe jest wyświetlany zgodnie ze specyfikacją interfejsu OpenAPI (openapi.json).

Interfejs Swagger można znaleźć na stronie https://localhost:<port>/swagger. Zapoznaj się z interfejsem API za pośrednictwem interfejsu użytkownika programu Swagger i uwzględnij go w innych programach.

Napiwek

Aby obsłużyć Swagger UI w katalogu głównym aplikacji (https://localhost:<port>/), ustaw właściwość RoutePrefix na pusty ciąg.

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Jeśli używasz katalogów z IIS lub zwrotnym serwerem proxy, ustaw punkt końcowy Swagger na ścieżkę względną przy użyciu prefiksu ./. Na przykład ./swagger/v1/swagger.json. Użycie /swagger/v1/swagger.json polecenia powoduje, że aplikacja wyszuka plik JSON w prawdziwym katalogu głównym adresu URL (oraz prefiks trasy, jeśli jest używany). Na przykład użyj polecenia https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json zamiast https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Uwaga

Domyślnie pakiet Swashbuckle generuje i udostępnia Swagger JSON w wersji 3.0 specyfikacji — oficjalnie nazywanej specyfikacją OpenAPI. Aby zapewnić zgodność wsteczną, możesz zdecydować się na udostępnienie JSON w formacie 2.0. Ten format 2.0 jest ważny w przypadku integracji, takich jak Microsoft Power Apps i Microsoft Flow, które obecnie obsługują interfejs OpenAPI w wersji 2.0. Aby włączyć format 2.0, ustaw właściwość SerializeAsV2 w Program.cs:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Dostosowywanie i rozszerzanie usługi

Program Swagger udostępnia opcje dokumentowania modelu obiektów i dostosowywania interfejsu użytkownika w celu dopasowania go do motywu.

Informacje i opis interfejsu API

Akcja konfiguracji przekazana do AddSwaggerGen metody dodaje informacje, takie jak autor, licencja i opis.

W Program.cs zaimportuj następującą przestrzeń nazw, aby użyć klasy OpenApiInfo.

using Microsoft.OpenApi.Models;

Za pomocą klasy zmodyfikuj OpenApiInfo informacje wyświetlane w interfejsie użytkownika:

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

Interfejs użytkownika Swagger wyświetla informacje o wersji:

Komentarze XML

Komentarze XML można włączyć przy użyciu następujących metod:

Visual Studio

• Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Edit <project_name>.csproj.
• Dodaj plik GenerateDocumentationFile 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.
• Dodaj plik GenerateDocumentationFile do .csproj pliku:

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

Visual Studio Code

Dodaj plik GenerateDocumentationFile do .csproj pliku:

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

.NET CLI

Dodaj plik GenerateDocumentationFile 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 składowe 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 'TodoController'

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 do $(NoWarn); powoduje również zastosowanie wartości domyślnych języka C#.

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

Aby pominąć ostrzeżenia tylko dla konkretnych elementów, należy ująć kod w dyrektywy 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. Wymuszanie kodu ostrzegawczego jest przywracane po zakończeniu definicji klasy. Określ wiele kodów ostrzegawczych z rozdzielaną przecinkami listą.

namespace SwashbuckleSample.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

Skonfiguruj program Swagger, aby używać pliku XML wygenerowanego z poprzednich instrukcji. Dla systemów operacyjnych Linux lub innych niż Windows, nazwy plików i ścieżki mogą rozróżniać wielkość liter. Na przykład plik TodoApi.XML jest prawidłowy w systemie Windows, ale nie na Ubuntu.

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

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

W poprzednim kodzie Reflection służy do kompilowania nazwy pliku XML zgodnej z nazwą projektu web API. Właściwość AppContext.BaseDirectory służy do konstruowania ścieżki do pliku XML. Niektóre funkcje struktury Swagger (na przykład schemat parametrów wejściowych lub metod HTTP i kodów odpowiedzi z odpowiednich atrybutów) działają bez użycia pliku dokumentacji XML. W przypadku większości funkcji, a mianowicie podsumowania metod i opisy parametrów i kodów odpowiedzi, użycie pliku XML jest obowiązkowe.

Dodawanie komentarzy z potrójnym ukośnikiem do akcji ulepsza interfejs Swagger UI, dodając opis do nagłówka sekcji. <Dodaj element podsumowania> powyżej Delete akcji:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

Interfejs użytkownika struktury Swagger wyświetla wewnętrzny tekst poprzedniego kodu <summary> :

Interfejs użytkownika jest napędzany przez wygenerowany schemat JSON:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Dodaj element <uwagi> do Create dokumentacji metody akcji. Uzupełnia informacje określone w elemencie <summary> i zapewnia bardziej rozbudowany interfejs użytkownika struktury Swagger. Zawartość <remarks> elementu może składać się z tekstu, kodu JSON lub XML.

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

Zwróć uwagę na ulepszenia interfejsu użytkownika z następującymi dodatkowymi komentarzami:

Adnotacje do danych

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

Dodaj atrybut [Required] do właściwości Name w klasie TodoItem.

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

namespace SwashbuckleSample.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:

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

[Produces("application/json")] Dodaj atrybut do kontrolera interfejsu API. Jego celem jest zadeklarowanie, że akcje kontrolera obsługują typ zawartości odpowiedzi aplikacji/json:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

Lista rozwijana Typ nośnika ustawia ten typ zawartości jako domyślny dla operacji GET kontrolera.

W miarę jak w internetowym interfejsie API rośnie użycie adnotacji danych, strony pomocy interfejsu użytkownika i API stają się bardziej opisowe i przydatne.

Opisywanie typów odpowiedzi

Deweloperzy korzystający z interfejsu API najbardziej interesują się tym, co jest zwracane—w szczególności typami odpowiedzi i kodami 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 ma wartość null. Bez odpowiedniej dokumentacji w interfejsie Swagger UI 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:

Konwencje mogą służyć jako alternatywa do bezpośredniego oznaczania poszczególnych czynności za pomocą [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Konwencje interfejsu API sieciowego.

Aby obsługiwać dekorację [ProducesResponseType], pakiet Swashbuckle.AspNetCore.Annotations oferuje rozszerzenia pozwalające na włączanie i wzbogacanie odpowiedzi, schematu oraz metadanych parametrów.

Dostosowywanie interfejsu użytkownika

Domyślny interfejs użytkownika jest zarówno funkcjonalny, jak i prezentowalny. Jednak strony dokumentacji interfejsu API powinny reprezentować twoją markę lub motyw. Personalizacja komponentów Swashbuckle wymaga dodania zasobów do obsługi plików statycznych oraz zbudowania struktury folderów do hostowania tych plików.

Włącz oprogramowanie pośredniczące plików statycznych:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Aby wstrzyknąć dodatkowe arkusze stylów CSS, dodaj je do folderu wwwroot projektu i określ ścieżkę względną w opcjach konfiguracji oprogramowania pośredniczącego.

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Ulepsz doświadczenie deweloperów API za pomocą dokumentacji Swagger