Wprowadzenie do pakietu Swashbuckle i platformy ASP.NET Core

Uwaga

Generowanie dokumentów OpenAPI w czasie kompilacji z pakietem Swashbuckle nie jest obsługiwane na platformie .NET 8 i nowszych wersjach. Aby uzyskać obsługiwaną alternatywę czasu kompilacji, zobacz dokumentację internetowego interfejsu API platformy ASP.NET Core za pomocą struktury Swagger/OpenAPI. Generowanie dokumentów w czasie wykonywania jest nadal obsługiwane na platformie .NET 8.

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 JSpunktów końcowych WŁ.

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

• Swashbuckle.AspNetCore.SwaggerUI: osadzona wersja narzędzia Swagger UI. Interpretuje narzędzie Swagger JSON w celu utworzenia rozbudowanego, dostosowywalnego środowiska do 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.5.0
    

• 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.5.0

.NET Core CLI

Uruchom następujące polecenie:

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

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 JSdokumentu ON i interfejsu użytkownika programu Swagger, również w programie 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 =>
    {
        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 JSplik ON 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 narzędzie Swagger JSON w wersji 3.0 specyfikacji — oficjalnie nazywane specyfikacją Interfejsu OpenAPI. Aby zapewnić zgodność z poprzednimi wersjami, możesz zamiast tego zdecydować się na uwidacznianie JSfunkcji ON 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>

.NET Core 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 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 Emocje ion służy do kompilowania nazwy pliku XML zgodnego 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 JSschemat ON:

"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, JSWŁ. 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 JSschemat ON:

"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 =>
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Program Swagger nie rozpoznaje komentarzy ani atrybutów rekordów
• Ulepszanie środowiska deweloperów interfejsu API za pomocą dokumentacji struktury Swagger