Udostępnij za pośrednictwem


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:

Instalacja pakietu

Pakiet Swashbuckle można dodać przy użyciu następujących metod:

  • 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

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:

Interfejs użytkownika programu Swagger z informacjami o wersji: opis, autor i licencja.

Komentarze XML

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

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

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 struktury Swagger przedstawiający komentarz XML

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:

Interfejs użytkownika struktury Swagger z wyświetlonymi 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:

Interfejs użytkownika struktury Swagger z domyślnym typem zawartości odpowiedzi

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:

Interfejs użytkownika struktury Swagger przedstawiający opis klasy odpowiedzi POST

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ć)

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

Instalacja pakietu

Pakiet Swashbuckle można dodać przy użyciu następujących metod:

  • 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 TodoApi.csproj istnieje plik

    • Wykonaj następujące polecenie:

      Install-Package Swashbuckle.AspNetCore -Version 5.6.3
      
  • 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

Dodawanie i konfigurowanie oprogramowania pośredniczącego struktury Swagger

Dodaj generator struktury Swagger do kolekcji usług w metodzie Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

W metodzie Startup.Configure włącz oprogramowanie pośredniczące do obsługi wygenerowanego dokumentu JSON i interfejsu użytkownika struktury Swagger:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
        app.UseSwaggerUI();
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Uwaga

Swashbuckle opiera się na wzorcach MVC Microsoft.AspNetCore.Mvc.ApiExplorer w celu odnajdywania tras i punktów końcowych. Jeśli projekt wywołuje AddMvcpolecenie , trasy i punkty końcowe zostaną automatycznie odnalezione. Podczas wywoływania AddMvcCoreAddApiExplorer metody metoda musi być jawnie wywoływana. Aby uzyskać więcej informacji, zobacz Swashbuckle, ApiExplorer i Routing.

W programowania poprzednie wywołanie UseSwaggerUI metody umożliwia osadzoną wersję narzędzia Swagger UI. Jest to zależne od oprogramowania pośredniczącego plików statycznych. W przypadku określania wartości docelowej dla programu .NET Framework lub .NET Core 1.x dodaj pakiet NuGet Microsoft.AspNetCore.StaticFiles do projektu.

Uruchom aplikację i przejdź do http://localhost:<port>/swagger/v1/swagger.json. 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 http://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 (http://localhost:<port>/), ustaw RoutePrefix właściwość na pusty ciąg:

// // UseSwaggerUI Protected by if (env.IsDevelopment())
app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.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 http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json zamiast http://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 Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger(c =>
        {
            c.SerializeAsV2 = true;
        });

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        // UseSwaggerUI is called only in Development.
        app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

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.

Startup W klasie dodaj następujące przestrzenie nazw:

using System;
using System.Reflection;
using System.IO;

Informacje i opis interfejsu API

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

W klasie zaimportuj Startup 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:

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });
});

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

Interfejs użytkownika programu Swagger z informacjami o wersji: opis, autor i zobacz więcej linków.

Komentarze XML

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

  • 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>
  <NoWarn>$(NoWarn);1591</NoWarn>
</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.GetAll()'

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 Program klasy. Wymuszanie kodu ostrzegawczego jest przywracane na zamknięciu definicji klasy. Określ wiele kodów ostrzegawczych z rozdzielaną przecinkami listą.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#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.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

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>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

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

Interfejs użytkownika struktury Swagger przedstawiający komentarz XML

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

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "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>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

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

Interfejs użytkownika struktury Swagger z wyświetlonymi 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 TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

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

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

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

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

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

Lista rozwijana Typ zawartości odpowiedzi wybiera ten typ zawartości jako domyślny dla akcji GET kontrolera:

Interfejs użytkownika struktury Swagger z domyślnym typem zawartości odpowiedzi.

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>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

Interfejs użytkownika struktury Swagger teraz wyraźnie dokumentuje oczekiwane kody odpowiedzi HTTP:

Interfejs użytkownika struktury Swagger przedstawiający opis klasy odpowiedzi POST

W ASP.NET Core 2.2 lub nowszych konwencje mogą być używane 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 przypadku określania wartości docelowej dla programu .NET Framework lub .NET Core 1.x dodaj pakiet NuGet Microsoft.AspNetCore.StaticFiles do projektu:

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.1.1" />

Poprzedni pakiet NuGet jest już zainstalowany, jeśli jest przeznaczony dla platformy .NET Core 2.x i używa metapakieta.

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

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseStaticFiles();

    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.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 (env.IsDevelopment())
{
    app.UseSwaggerUI(c =>
    {
        c.InjectStylesheet("/swagger-ui/custom.css");
    }
}

Dodatkowe zasoby