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

Swashbuckle má tři hlavní komponenty:

• Swashbuckle. AspNetCore. Swagger: objektový model a middleware pro objekty Swagger k vystavení SwaggerDocument objektů jako koncových bodů JSON.

• Swashbuckle. AspNetCore. SwaggerGen: generátor Swagger, který vytváří SwaggerDocument objekty přímo z vašich tras, řadičů a modelů. Obvykle funguje tak, že v kombinaci s middlewarem koncových bodů Swaggeru automaticky zveřejňuje kód JSON pro Swagger.

• Swashbuckle. AspNetCore. SwaggerUI: vložená verze nástroje uživatelského rozhraní Swagger. Interpretuje JSON pro Swagger v podobě propracované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 je možné přidat s následujícími přístupy:

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

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

Přidat a nakonfigurovat middleware Swagger

Přidejte generátor Swagger do kolekce Services v programu program. cs:

builder.Services.AddControllers();

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

Povolte middleware pro obsluhu generovaného dokumentu JSON a uživatelského rozhraní Swagger, a to i v programu 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í nastaveno na vývoj. UseSwaggerUIVolání metody umožňuje middleware statického souboru.

Spusťte aplikaci a přejděte na adresu https://localhost:<port>/swagger/v1/swagger.json . Vygenerovaný dokument popisující koncové body se zobrazí, jak je uvedeno v openapi Specification (openapi. JSON).

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

app.UseSwaggerUI(options =>
{
    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 Swagger na relativní cestu pomocí ./ předpony. Například, ./swagger/v1/swagger.json. Pomocí nástroje /swagger/v1/swagger.json instruuje aplikaci, aby hledala soubor JSON na skutečném kořenu adresy URL (plus předpona trasy, pokud se používá). Můžete například namísto https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json použít https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

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

Přizpůsobení a rozšiřování

Swagger poskytuje možnosti pro dokumentaci k objektovému 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 programu program. cs importujte následující obor názvů pro použití OpenApiInfo třídy:

using Microsoft.OpenApi.Models;

Pomocí OpenApiInfo 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 zobrazuje informace o verzi:

Komentáře XML

Komentáře XML lze povolit pomocí následujících přístupů:

Povolení komentářů XML poskytuje ladicí informace pro nedokumentované veřejné typy a členy. Nedokumentované typy a členy jsou označeny varovnou zprávou. 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í v rámci projektu, definujte seznam kódů upozornění oddělených středníkem, které mají být v souboru projektu ignorovány. Připojení kódů upozornění k $(NoWarn); použití výchozích hodnot jazyka C# .

Chcete-li potlačit upozornění pouze pro konkrétní členy, uveďte kód v direktivách preprocesoru upozornění #pragma . Tento přístup je užitečný pro kód, který by neměl být zveřejněn prostřednictvím dokumentace rozhraní API. V následujícím příkladu je kód upozornění CS1591 ignorován pro celou TodoContext třídu. Vynucování kódu upozornění je obnoveno při zavření 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 pro použití souboru XML, který je vygenerovaný předchozími pokyny. u operačních systémů Linux nebo non Windows se může u názvů souborů a cest rozlišovat velká a malá písmena. například TodoApi.XML soubor je platný v Windows, ale ne 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));
});

V předchozím kódu se reflexe používá k sestavení názvu souboru XML, který odpovídá tomuto projektu webového rozhraní API. Vlastnost AppContext. BaseDirectory se používá k vytvoření cesty k souboru XML. Některé funkce Swagger (například schémat vstupních parametrů nebo metody HTTP a kódy odpovědí z příslušných atributů) fungují bez použití souboru dokumentace XML. Pro většinu funkcí, konkrétně souhrny metod a popisy 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. Přidejte <summary> element nad Delete akci:

/// <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 elementu předchozí kód <summary> :

Uživatelské rozhraní je založené na generovaném schématu 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"
        }
    }
},

Přidejte <remarks> element do dokumentace k Create metodě akce. Doplňuje informace zadané v <summary> prvku a poskytuje robustnější uživatelské rozhraní Swagger. <remarks>Obsah 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í pomocí těchto dalších komentářů:

Datové poznámky

Označte model atributy, které najdete v oboru názvů System.ComponentModel.DataAnnotations, abyste pomohli řídit komponenty uživatelského rozhraní Swagger.

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

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í schéma JSON:

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

Přidejte [Produces("application/json")] 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 tím, jak se zvyšuje využití datových poznámek ve webovém rozhraní API, jsou stránky nápovědy uživatelského rozhraní a rozhraní API popisnější a užitečnější.

Popis typů odpovědí

Vývojáři, kteří spotřebovávají webové rozhraní API, se nejvíce obává vrácených konkrétních typů odpovědí a kódů chyb — (pokud ne standardní). Typy odpovědí a kódy chyb jsou v komentářích XML a datových poznámkách označeny.

Akce při úspěchu vrátí stavový kód Create HTTP 201. Stavový kód HTTP 400 se vrátí, když má tělo požadavku posted hodnotu null. Bez správné dokumentace v uživatelském rozhraní Swaggeru spotřebitel nemá o těchto očekávaných výsledcích znalosti. Opravte tento problém 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);
}

Swagger UI teď jasně dokumentovat očekávané kódy odpovědí HTTP:

Konvence lze použít jako alternativu k explicitnímu vytyčování jednotlivých akcí pomocí [ProducesResponseType] . Další informace naleznete v tématu Použití konvencí webového rozhraní API.

Pro podporu [ProducesResponseType] dekorování balíček Swashbuckle.AspNetCore.Annotations nabízí rozšíření pro povolení a rozšíření odpovědí, schématu a metadat 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 sestavení struktury složek pro hostování těchto souborů.

Povolení middlewaru statického souboru:

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:

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

Další zdroje informací

• Microsoft Learn: Vylepšení vývojářského prostředí rozhraní API pomocí dokumentace Swaggeru

Swashbuckle má tři hlavní komponenty:

• Swashbuckle.AspNetCore.Swagger:Objektový model Swaggeru a middleware pro vystavení objektů SwaggerDocument jako koncových bodů JSON.

• Swashbuckle.AspNetCore.SwaggerGen:Generátor Swagger, který vytváří objekty přímo z SwaggerDocument tras, kontrolerů a modelů. Obvykle funguje tak, že v kombinaci s middlewarem koncových bodů Swaggeru automaticky zveřejňuje kód JSON pro Swagger.

• Swashbuckle.AspNetCore.SwaggerUI:vložená verze nástroje Swagger UI. Interpretuje JSON pro Swagger v podobě propracované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 je možné přidat s následujícími přístupy:

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

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

Přidání a konfigurace middlewaru Swagger

Přidejte generátor Swagger do kolekce služeb v Startup.ConfigureServices metodě :

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

V Startup.Configure metodě povolte middleware pro obsluhu generovaného dokumentu JSON a uživatelského rozhraní Swaggeru:

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

Předchozí volání UseSwaggerUI metody povoluje middleware statického souboru. Pokud cílíte .NET Framework nebo .NET Core 1.x, přidejte do projektu NuGet Microsoft.AspNetCore.StaticFiles.

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

Uživatelské rozhraní Swaggeru najdete na adrese http://localhost:<port>/swagger . Prozkoumejte rozhraní API přes Swagger UI a začleňujete ho do jiných programů.

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.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í instruuje aplikaci, aby v kořenovém adresáři adresy URL ve skutečném kořenovém adresáři (plus předponu trasy, pokud /swagger/v1/swagger.json se používá) našli soubor JSON. Můžete například namísto http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json použít http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

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

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

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

Do Startup třídy přidejte následující obory názvů:

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

Informace a popis rozhraní API

Konfigurační akce předaná AddSwaggerGen metodě přidá informace, jako je autor, licence a popis:

Ve třídě Startup naimportujte následující obor názvů pro použití OpenApiInfo třídy :

using Microsoft.OpenApi.Models;

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

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

Swagger UI zobrazí informace o verzi:

Komentáře XML

Komentáře XML lze povolit s následujícími přístupy:

Povolení komentářů XML poskytuje ladicí informace pro nedokumentované veřejné typy a členy. Nedokumentované typy a členy jsou označeny varovnou zprávou. 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.GetAll()'

Chcete-li potlačit upozornění v rámci projektu, definujte seznam kódů upozornění oddělených středníkem, které mají být v souboru projektu ignorovány. Připojení kódů upozornění k $(NoWarn); použití výchozích hodnot jazyka C# .

Chcete-li potlačit upozornění pouze pro konkrétní členy, uveďte kód v direktivách preprocesoru upozornění #pragma . Tento přístup je užitečný pro kód, který by neměl být zveřejněn prostřednictvím dokumentace rozhraní API. V následujícím příkladu je kód upozornění CS1591 ignorován pro celou Program třídu. Vynucování kódu upozornění je obnoveno při zavření definice třídy. Zadejte více kódů upozornění se seznamem odděleným čárkami.

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
}

Nakonfigurujte Swagger pro použití souboru XML, který je vygenerovaný předchozími pokyny. u operačních systémů Linux nebo non Windows se může u názvů souborů a cest rozlišovat velká a malá písmena. například TodoApi.XML soubor je platný v Windows, ale ne 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);
    });
}

V předchozím kódu se reflexe používá k sestavení názvu souboru XML, který odpovídá tomuto projektu webového rozhraní API. Vlastnost AppContext. BaseDirectory se používá k vytvoření cesty k souboru XML. Některé funkce Swagger (například schémat vstupních parametrů nebo metody HTTP a kódy odpovědí z příslušných atributů) fungují bez použití souboru dokumentace XML. Pro většinu funkcí, konkrétně souhrny metod a popisy 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. Přidejte <summary> element nad Delete akci:

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

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

Uživatelské rozhraní je založené na generovaném schématu 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"
        }
    }
}

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

Všimněte si vylepšení uživatelského rozhraní pomocí těchto dalších komentářů:

Datové poznámky

Označte model s atributy, které se nacházejí v oboru názvů System. ComponentModel. DataAnnotations , aby bylo možné lépe řídit součásti uživatelského rozhraní Swagger.

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

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

Přítomnost tohoto atributu mění chování uživatelského rozhraní a mění základní schéma JSON:

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

Přidejte [Produces("application/json")] atribut do kontroleru rozhraní API. Jeho účelem je deklarovat, že akce kontroleru podporují typ obsahu odpovědi Application/JSON:

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

Rozevírací seznam typ obsahu odpovědi pro akce GET kontroleru vybere tento typ obsahu jako výchozí:

Díky nárůstu využití datových poznámek ve webovém rozhraní API se stránky s nápovědu pro uživatelské rozhraní a rozhraní API stanou výstižnější a užitečnější.

Popis typů odpovědí

Vývojáři, kteří využívají webové rozhraní API, mají největší obavy s tím, co vrací — konkrétně typy odpovědí a kódy chyb (Pokud ne Standard). Typy odpovědí a kódy chyb jsou označeny v komentářích XML a datových anotacích.

CreateAkce vrátí stavový kód HTTP 201 při úspěchu. Stavový kód HTTP 400 se vrátí, když text odeslaného požadavku má hodnotu null. Bez správné dokumentace v uživatelském rozhraní Swagger nemá spotřebitel znalosti o těchto očekávaných výsledcích. Opravte tento problém tak, že přidáte zvýrazněné řádky v následujícím příkladu:

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

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

v ASP.NET Core 2,2 nebo novějších lze konvence použít jako alternativu k explicitnímu upraveníí jednotlivých akcí [ProducesResponseType] . Další informace naleznete v tématu Použití konvencí webového rozhraní API.

Pro podporu [ProducesResponseType] dekorace nabízí balíček swashbuckle. AspNetCore. anotace rozšíření, která umožňují a rozšiřují metadata, schéma a parametry metadat.

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

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

pokud cílíte .NET Framework nebo .net Core 1. x, přidejte do projektu balíček Microsoft. AspNetCore. StaticFiles NuGet:

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

předchozí balíček NuGet je již nainstalován, pokud cílíte na rozhraní .net Core 2. x a použijete metapackage.

Povolit middleware statických souborů:

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

Chcete-li vložit další šablony stylů CSS, přidejte je do složky wwwroot projektu a zadejte relativní cestu do možností middlewaru:

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

Další zdroje informací

• Microsoft Learn: zlepšení prostředí pro vývojáře rozhraní API pomocí dokumentace k Swagger