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ć alternatywę, zobacz Omówienie obsługi interfejsu OpenAPI w aplikacjach interfejsu API platformy ASP.NET Core.

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

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

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

• Swashbuckle.AspNetCore.SwaggerUI: osadzona wersja narzędzia Swagger UI. Interpretuje kod JSON programu Swagger w celu tworzenia rozbudowanych, możliwych do dostosowania środowisk na potrzeby opisywania funkcji internetowego interfejsu API. Obejmuje wbudowane kontrolery testów dla metod publicznych.

Instalacja pakietu

Pakiet Swashbuckle można dodać przy użyciu 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 .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 >rozwiązania 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

Interfejs wiersza polecenia platformy .NET

Uruchom następujące polecenie:

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

Dodawanie i konfigurowanie oprogramowania pośredniczącego struktury Swagger

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

builder.Services.AddControllers();

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

Wywołanie pokazane AddEndpointsApiExplorer w poprzednim przykładzie jest wymagane tylko dla minimalnych interfejsów 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 oprogramowanie pośredniczące struktury Swagger tylko wtedy, gdy bieżące środowisko ma wartość Programowanie. 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 użytkownika struktury 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ć interfejs użytkownika struktury Swagger w katalogu głównym aplikacji (https://localhost:<port>/), ustaw RoutePrefix właściwość 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 usługami IIS lub zwrotnym serwerem proxy, ustaw punkt końcowy programu 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 uwidacznia kod JSON struktury Swagger w wersji 3.0 specyfikacji — oficjalnie nazywany specyfikacją interfejsu OpenAPI. Aby zapewnić zgodność z poprzednimi wersjami, możesz zdecydować się na uwidacznianie formatu 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 wybrać format 2.0, ustaw SerializeAsV2 właściwość w pliku 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.cspliku zaimportuj następującą przestrzeń nazw, aby użyć OpenApiInfo klasy :

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

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

Komentarze XML

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

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

Interfejs wiersza polecenia platformy .NET

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 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 '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 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 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. W przypadku systemów operacyjnych Linux lub innych niż Windows nazwy plików i ścieżki mogą mieć wielkość liter. Na przykład plik jest prawidłowy w systemie Windows, TodoApi.XML ale nie 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 odbicie służy do kompilowania nazwy pliku XML zgodnej z nazwą projektu internetowego interfejsu 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 do akcji komentarzy z potrójnym ukośnikiem ulepsza wyniki narzędzia Swagger UI przez dodanie opisu 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 elemplecie <summary> i zapewnia bardziej niezawodny 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, 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 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 wybiera ten typ zawartości jako domyślny dla akcji GET kontrolera:

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 ma wartość 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:

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.

Aby obsługiwać dekorację [ProducesResponseType] , pakiet Swashbuckle.AspNetCore.Annotations oferuje rozszerzenia umożliwiające włączanie i wzbogacanie odpowiedzi, schematu i 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. Oznaczanie składników swashbuckle wymaga dodania zasobów do obsługi plików statycznych i utworzenia 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 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ć)
• Ulepszanie środowiska deweloperów interfejsu API za pomocą dokumentacji struktury Swagger