Začínáme s Swashbuckle a ASP.NET Core

Poznámka:

Generování dokumentů OpenAPI v čase sestavení pomocí Swashbuckle není v .NET 8 a novějších podporovaných. Podporovanou alternativu k sestavení najdete v dokumentaci k webovému rozhraní API pro ASP.NET Core pomocí Swaggeru nebo OpenAPI. Generování dokumentů za běhu je stále podporováno v .NET 8.

Swashbuckle má tři hlavní komponenty:

• Swashbuckle.AspNetCore.Swagger: objektový model Swaggeru a middleware, který zpřístupňuje SwaggerDocument objekty jako JSkoncové body ON.

• Swashbuckle.AspNetCore.SwaggerGen: generátor Swagger, který vytváří SwaggerDocument objekty přímo z vašich tras, kontrolerů a modelů. Obvykle se kombinuje s middlewarem koncového bodu Swagger, který automaticky zveřejňuje Swagger JSON.

• Swashbuckle.AspNetCore.SwaggerUI: vložená verze nástroje Swagger UI. Interpretuje Swagger JSON za účelem vytvoření bohatého přizpůsobitelného prostředí pro popis funkcí webového rozhraní API. Jeho součástí je i integrovaný správce testů pro veřejné metody.

Instalace balíčku

Swashbuckle lze přidat pomocí následujících přístupů:

Visual Studio

• V okně konzoly Správce balíčků:

  • Přejděte do zobrazení>jiné konzoly windows Správce balíčků>

  • Přejděte do adresáře, ve kterém .csproj soubor existuje.

  • Spusťte následující příkaz:

    Install-Package Swashbuckle.AspNetCore -Version 6.5.0
    

• V dialogovém okně Spravovat balíčky NuGet:

  • Klikněte pravým tlačítkem na projekt v balíčku NuGet Průzkumník řešení> Manage
  • Nastavte zdroj balíčku na nuget.org.
  • Ujistěte se, že je povolená možnost Zahrnout předběžné verze.
  • Do vyhledávacího pole zadejte Swashbuckle.AspNetCore.
  • Na kartě Procházet vyberte nejnovější balíček Swashbuckle.AspNetCore a klikněte na Nainstalovat.

Visual Studio pro Mac

• Klikněte pravým tlačítkem na složku Packages (Balíčky) v oblasti>řešení Přidat balíčky...
• V rozevíracím seznamu Zdroj v okně Přidat balíčky nastavte nuget.org.
• Ujistěte se, že je povolená možnost Zobrazit předběžné verze balíčků.
• Do vyhledávacího pole zadejte Swashbuckle.AspNetCore.
• V podokně výsledků vyberte nejnovější balíček Swashbuckle.AspNetCore a klikněte na Přidat balíček.

Visual Studio Code

Z integrovaného terminálu spusťte následující příkaz:

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

Rozhraní příkazového řádku .NET Core

Spusťte následující příkaz:

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

Přidání a konfigurace middlewaru Swaggeru

Přidejte generátor Swaggeru do kolekce služeb v Program.cs:

builder.Services.AddControllers();

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

Volání, které se AddEndpointsApiExplorer zobrazí v předchozím příkladu, se vyžaduje pouze pro minimální rozhraní API. Další informace najdete v tomto příspěvku StackOverflow.

Povolte middleware pro obsluhu vygenerovaného JSdokumentu ON a uživatelského rozhraní Swagger, a to také v Program.cs:

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

Předchozí kód přidá middleware Swagger pouze v případě, že je aktuální prostředí nastavené na Vývoj. Volání UseSwaggerUI metody umožňuje vloženou verzi nástroje Swagger UI.

Spusťte aplikaci a přejděte na https://localhost:<port>/swagger/v1/swagger.json. Vygenerovaný dokument popisující koncové body se zobrazí, jak je znázorněno ve specifikaci OpenAPI (openapi.json).

Swagger UI najdete na adrese https://localhost:<port>/swagger. Prozkoumejte rozhraní API prostřednictvím uživatelského rozhraní Swagger a začleňte ho do jiných programů.

Tip

Pokud chcete obsluhovat uživatelské rozhraní Swaggeru v kořenovém adresáři aplikace (https://localhost:<port>/), nastavte RoutePrefix vlastnost na prázdný řetězec:

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

Pokud používáte adresáře se službou IIS nebo reverzním proxy serverem, nastavte koncový bod Swaggeru na relativní cestu pomocí předpony ./ . Například ./swagger/v1/swagger.json. Použití /swagger/v1/swagger.json dává aplikaci pokyn, aby hledala JSsoubor ON v kořenovém adresáři adresy URL (plus předpona trasy, pokud se používá). Například místo https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json .https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json

Poznámka:

Ve výchozím nastavení Swashbuckle generuje a zveřejňuje Swagger JSON ve verzi 3.0 specifikace – oficiálně se nazývá Specifikace OpenAPI. Pokud chcete podporovat zpětnou kompatibilitu, můžete se místo toho přihlásit k zveřejnění JSfunkce ON ve formátu 2.0. Tento formát 2.0 je důležitý pro integrace, jako jsou Microsoft Power Apps a Microsoft Flow, které aktuálně podporují OpenAPI verze 2.0. Chcete-li se přihlásit do formátu 2.0, nastavte SerializeAsV2 vlastnost v Program.cs:

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

Přizpůsobení a rozšíření

Swagger nabízí možnosti pro dokumentaci objektového modelu a přizpůsobení uživatelského rozhraní tak, aby odpovídalo vašemu motivu.

Informace a popis rozhraní API

Akce konfigurace předaná AddSwaggerGen metodě přidá informace, jako je autor, licence a popis.

V Program.csaplikaci naimportujte následující obor názvů pro použití OpenApiInfo třídy:

using Microsoft.OpenApi.Models;

OpenApiInfo Pomocí třídy upravte informace zobrazené v uživatelském rozhraní:

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

Uživatelské rozhraní Swagger zobrazí informace o verzi:

Komentáře XML

Komentáře XML je možné povolit pomocí následujících přístupů:

Visual Studio

• Klikněte pravým tlačítkem myši na projekt v Průzkumník řešení a vyberte Edit <project_name>.csproj.
• Přidejte do .csproj souboru soubor GenerateDocumentationFile:

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

Visual Studio pro Mac

• Na panelu řešení stiskněte ovládací prvek a klikněte na název projektu. Přejděte do části Nástroje>upravit soubor.
• Přidejte do .csproj souboru soubor GenerateDocumentationFile:

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

Visual Studio Code

Přidejte do .csproj souboru soubor GenerateDocumentationFile:

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

Rozhraní příkazového řádku .NET Core

Přidejte do .csproj souboru soubor GenerateDocumentationFile:

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

Povolení komentářů XML poskytuje informace o ladění pro nezdokumentované veřejné typy a členy. Nezdokumentované typy a členy jsou označeny upozorněním. Například následující zpráva indikuje porušení kódu upozornění 1591:

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

Chcete-li potlačit upozornění na úrovni projektu, definujte seznam kódů upozornění oddělených středníkem, které se mají v souboru projektu ignorovat. Připojte kódy upozornění, aby $(NoWarn); se použily i výchozí hodnoty jazyka C#.

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

Chcete-li potlačit upozornění pouze pro konkrétní členy, uzavřete kód do #pragma direktivy preprocesoru upozornění . Tento přístup je užitečný pro kód, který by neměl být zpřístupněn prostřednictvím dokumentace k rozhraní API. V následujícím příkladu je kód upozornění CS1591 ignorován pro celou TodoContext třídu. Vynucení kódu upozornění se obnoví na konci definice třídy. Zadejte více kódů upozornění se seznamem odděleným čárkami.

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

Nakonfigurujte Swagger tak, aby používal soubor XML vygenerovaný pomocí předchozích pokynů. U operačních systémů Linux nebo jiných systémů než Windows můžou být názvy souborů a cesty rozlišovat velká a malá písmena. Například TodoApi.XML soubor je platný ve Windows, ale ne 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));
});

V předchozím kódu se Reflexe ion používá k vytvoření názvu souboru XML odpovídajícího projektu webového rozhraní API. Vlastnost AppContext.BaseDirectory slouží k vytvoření cesty k souboru XML. Některé funkce Swaggeru (například schéma vstupních parametrů nebo metod HTTP a kódů odpovědí z příslušných atributů) fungují bez použití souboru dokumentace XML. U většiny funkcí, konkrétně souhrnů metod a popisů parametrů a kódů odpovědí, je použití souboru XML povinné.

Můžete k akci přidat také komentáře uvozené třemi lomítky, a vylepšit tak Swagger UI tím, že přidáte popis do hlavičky oddílu. <Nad akci přidejte souhrnný> prvekDelete:

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

Uživatelské rozhraní Swagger zobrazí vnitřní text předchozího prvku kódu <summary> :

Uživatelské rozhraní je řízené vygenerovaným JSschématem 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"
        }
    }
},

<Přidejte do dokumentace k metodě akce prvek Create poznámek>. Doplňuje informace zadané v <summary> prvku a poskytuje robustnější uživatelské rozhraní Swagger. Obsah <remarks> elementu se může skládat z textu, JSON nebo 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);
}

Všimněte si vylepšení uživatelského rozhraní s těmito dalšími komentáři:

Datové poznámky

Označte model pomocí atributů nalezených v System.ComponentModel.DataAnnotations oboru názvů, který pomáhá řídit komponenty uživatelského rozhraní Swagger.

[Required] Přidejte atribut do Name vlastnosti TodoItem třídy:

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

Přítomnost tohoto atributu změní chování uživatelského rozhraní a změní základní JSschéma 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")] Přidejte atribut do kontroleru rozhraní API. Jejím účelem je deklarovat, že akce kontroleru podporují typ obsahu odpovědi application/json:

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

Rozevírací seznam Typ média vybere tento typ obsahu jako výchozí pro akce GET kontroleru:

S rostoucím využitím datových poznámek ve webovém rozhraní API se stránky nápovědy k uživatelskému rozhraní a rozhraní API stanou popisnější a užitečnější.

Popis typů odpovědí

Vývojáři, kteří využívají webové rozhraní API, se nejvíce zajímají o to, co se vrátí – konkrétně typy odpovědí a kódy chyb (pokud nejsou standardní). Typy odpovědí a kódy chyb jsou označené v komentářích XML a datových poznámkách.

Akce Create vrátí stavový kód HTTP 201 při úspěchu. Stavový kód HTTP 400 se vrátí, když text publikovaného požadavku má hodnotu null. Bez správné dokumentace v uživatelském rozhraní Swaggeru spotřebitel nemá znalosti o těchto očekávaných výsledcích. Tento problém opravte přidáním zvýrazněných řádků v následujícím příkladu:

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

Uživatelské rozhraní Swagger teď jasně dokumentuje očekávané kódy odpovědí HTTP:

Konvence lze použít jako alternativu k explicitní dekódování jednotlivých akcí pomocí [ProducesResponseType]. Další informace najdete v tématu Použití konvencí webového rozhraní API.

Pro podporu [ProducesResponseType] dekorace nabízí balíček Swashbuckle.AspNetCore.Annotations rozšíření pro povolení a obohacení metadat odpovědí, schémat a parametrů.

Přizpůsobení uživatelského rozhraní

Výchozí uživatelské rozhraní je funkční i prezentovatelné. Stránky dokumentace k rozhraní API by ale měly představovat vaši značku nebo motiv. Branding komponent Swashbuckle vyžaduje přidání prostředků pro obsluhu statických souborů a vytvoření struktury složek pro hostování těchto souborů.

Povolení middlewaru statických souborů:

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

Pokud chcete vložit další šablony stylů CSS, přidejte je do složky wwwroot projektu a v možnostech middlewaru zadejte relativní cestu:

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

Další materiály

• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Swagger nerozpozná komentáře ani atributy u záznamů
• Vylepšení vývojářského prostředí rozhraní API pomocí dokumentace ke Swaggeru