Wprowadzenie do struktury Swashbuckle i ASP.NET Core

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

  • Swashbuckle.AspNetCore.Swagger: model obiektów struktury Swagger i oprogramowanie pośredniczące do uwidocznienia SwaggerDocument obiektów jako JSpunktów końcowych WŁ.

  • Swashbuckle.AspNetCore.SwaggerGen: generator struktury Swagger, który tworzy SwaggerDocument obiekty bezpośrednio z tras, kontrolerów i modeli. Zwykle jest ona połączona z oprogramowaniem pośredniczącym punktu końcowego struktury 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:

  • W oknie Konsola Menedżera pakietów :

    • Przejdź do pozycji Wyświetl> innąkonsolę Menedżera pakietówsystemu Windows>

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

    • Uruchom następujące polecenie:

      Install-Package Swashbuckle.AspNetCore -Version 6.2.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 pliku Program.cs:

builder.Services.AddControllers();

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

Włącz oprogramowanie pośredniczące do obsługi wygenerowanego JSdokumentu ON i interfejsu użytkownika struktury 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 oprogramowanie pośredniczące w plikach statycznych.

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źć pod adresem https://localhost:<port>/swagger. Zapoznaj się z interfejsem API za pośrednictwem interfejsu użytkownika programu Swagger i uwzględnij go w innych programach.

Porada

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:

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. Za pomocą /swagger/v1/swagger.json polecenia aplikacja wyszukuje JSplik ON w prawdziwym katalogu głównym adresu URL (plus prefiks trasy, jeśli jest używany). Na przykład: użyj opcji https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json zamiast https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Uwaga

Domyślnie swashbuckle generuje i uwidacznia narzędzie Swagger JSON w wersji 3.0 specyfikacji — oficjalnie nazywane specyfikacją OpenAPI. Aby zapewnić zgodność z poprzednimi wersjami, możesz zamiast tego zdecydować się na uwidacznianie JSopcji WŁĄCZONE 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

Program Swagger udostępnia opcje dokumentowania modelu obiektów i dostosowywania interfejsu użytkownika w celu dopasowania 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ą OpenApiInfo przestrzeń nazw, aby użyć klasy:

using Microsoft.OpenApi.Models;

Przy użyciu 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 struktury Swagger wyświetla 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 o debugowaniu 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 ostrzegawczego 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Aby pominąć ostrzeżenia dla całego projektu, zdefiniuj rozdzieloną średnikami listę kodów ostrzegawczych do zignorowania 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ć uwidoczniony 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 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 przy użyciu powyższych 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 CentOS.

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 pasującej do nazwy 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 elementu kodu <summary> :

Interfejs użytkownika struktury Swagger przedstawiający komentarz XML

Interfejs użytkownika jest sterowany 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 <summary> elemecie 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:

Interfejs użytkownika struktury Swagger z wyświetlonymi dodatkowymi komentarzami.

Adnotacje danych

Oznacz model atrybutami znajdującymi się w System.ComponentModel.DataAnnotations przestrzeni nazw, aby ułatwić napędzanie składników interfejsu 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:

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

Wraz ze wzrostem 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ą 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 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:

Narzędzie Swagger UI z opisem klasy odpowiedzi POST

Konwencje mogą służyć jako alternatywa dla 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 metadanych odpowiedzi, schematu i parametru.

Dostosowywanie interfejsu użytkownika

Domyślny interfejs użytkownika jest funkcjonalny i dostępny. Jednak strony dokumentacji interfejsu API powinny reprezentować twoją markę lub motyw. Oznaczanie składników pakietu Swashbuckle wymaga dodania zasobów do obsługi plików statycznych i utworzenia struktury folderów w celu 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 :

app.UseSwaggerUI(options =>
{
    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:

  • Swashbuckle.AspNetCore.Swagger: model obiektów i oprogramowanie pośredniczące 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 struktury Swagger, aby automatycznie uwidocznić strukturę Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: osadzona wersja narzędzia Swagger UI. Interpretuje platformę 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:

  • W oknie Konsola menedżera pakietów :

    • Przejdź do pozycji Wyświetl>innąkonsolę Menedżera pakietów systemu Windows >

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

    • Uruchom 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 JSdokumentu ON i interfejsu użytkownika struktury Swagger:

public void Configure(IApplicationBuilder app)
{
    // 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

Pakiet Swashbuckle korzysta z wzorca MVC Microsoft.AspNetCore.Mvc.ApiExplorer do odnajdywania tras i punktów końcowych. Jeśli projekt wywołuje AddMvcmetodę , trasy i punkty końcowe zostaną wykryte automatycznie. Podczas wywoływania AddMvcCoremetody należy jawnie wywołać metodę AddApiExplorer . Aby uzyskać więcej informacji, zobacz Swashbuckle, ApiExplorer i Routing.

Poprzednie wywołanie UseSwaggerUI metody umożliwia korzystanie z oprogramowania pośredniczącego plików statycznych. W przypadku określania wartości docelowej .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.jsonadresu . Wygenerowany dokument opisujący punkty końcowe jest wyświetlany w specyfikacji interfejsu OpenAPI (openapi.json).

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

Porada

Aby obsługiwać interfejs użytkownika struktury Swagger w katalogu głównym aplikacji (http://localhost:<port>/), ustaw RoutePrefix właściwość na pusty ciąg:

app.UseSwaggerUI(c =>
{
    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 struktury 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 wyszukuje JSplik ON w prawdziwym katalogu głównym adresu URL (oraz prefiks trasy, jeśli jest używany). Na przykład: użyj opcji 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 narzędzie Swagger JSON w wersji 3.0 specyfikacji — oficjalnie nazywane specyfikacją OpenAPI. Aby zapewnić zgodność z poprzednimi wersjami, możesz zamiast tego zdecydować się na uwidocznianie JSopcji WŁĄCZONE 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)
{
    // 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.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

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

Dostosowywanie i rozszerzanie

Struktura 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:

Narzędzie Swagger UI 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 ostrzegawczego 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Aby pominąć ostrzeżenia dla całego projektu, zdefiniuj rozdzieloną średnikami listę kodów ostrzeżeń do zignorowania 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 dyrektywy preprocesora ostrzegawczego #pragma . Takie podejście jest przydatne w przypadku kodu, który nie powinien być uwidaczniony 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 ostrzeżeń z listą rozdzielaną przecinkami.

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 do używania pliku XML wygenerowanego przy użyciu powyższych instrukcji. W przypadku systemów operacyjnych Linux lub innych niż Windows w nazwach plików i ścieżkach może być rozróżniana wielkość liter. Na przykład plik jest prawidłowy w systemie Windows, TodoApi.XML ale nie w systemie CentOS.

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 tworzenia 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 elementu kodu <summary> :

Narzędzie Swagger UI z komentarzem XML

Interfejs użytkownika jest sterowany przez wygenerowany JSschemat ON:

"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 elemecie <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>
/// <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 danych

Oznacz model atrybutami znajdującymi się w System.ComponentModel.DataAnnotations przestrzeni nazw, aby ułatwić napędzanie składników interfejsu 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 JSschemat ON:

"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.

Wraz ze wzrostem 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ą 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 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:

Narzędzie Swagger UI z opisem klasy odpowiedzi POST

W ASP.NET Core 2.2 lub nowszej konwencje mogą służyć jako alternatywa dla 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 metadanych odpowiedzi, schematu i parametru.

Dostosowywanie interfejsu użytkownika

Domyślny interfejs użytkownika jest funkcjonalny i dostępny. Jednak strony dokumentacji interfejsu API powinny reprezentować twoją markę lub motyw. Oznaczanie składników pakietu Swashbuckle wymaga dodania zasobów do obsługi plików statycznych i utworzenia struktury folderów w celu hostowania tych plików.

W przypadku określania wartości docelowej .NET Framework lub .NET Core 1.x dodaj pakiet NuGet Microsoft.AspNetCore.StaticFiles do projektu:

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

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)
{
    app.UseStaticFiles();

    // 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 =>
    {
        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 :

app.UseSwaggerUI(c =>
{
     c.InjectStylesheet("/swagger-ui/custom.css");
}

Dodatkowe zasoby