Aan de slag met Swashbuckle en ASP.NET Core

Notitie

Swashbuckle is niet beschikbaar in .NET 9 of hoger. Zie Overzicht van OpenAPI-ondersteuning in ASP.NET Core API-appsvoor een alternatief.

Er zijn drie hoofdonderdelen voor Swashbuckle:

• Swashbuckle.AspNetCore.Swagger-: een Swagger-objectmodel en middleware om SwaggerDocument objecten beschikbaar te maken als JSON-eindpunten.

• Swashbuckle.AspNetCore.SwaggerGen: een Swagger-generator waarmee SwaggerDocument objecten rechtstreeks vanuit uw routes, controllers en modellen worden gebouwd. Dit wordt meestal gecombineerd met de Swagger-eindpunt-middleware om Swagger JSON automatisch beschikbaar te maken.

• Swashbuckle.AspNetCore.SwaggerUI: een ingesloten versie van het hulpprogramma Swagger UI. Het interpreteert Swagger JSON om een uitgebreide, aanpasbare ervaring te bouwen voor het beschrijven van de web-API-functionaliteit. Het bevat ingebouwde testharnasen voor de openbare methoden.

Pakketinstallatie

Swashbuckle kan worden toegevoegd op de volgende manieren:

Visual Studio

• Vanuit het venster Package Manager Console:

  • Ga naar View>Andere Vensters>Package Manager Console

  • Navigeer naar de map waarin het .csproj bestand bestaat

  • Voer de volgende opdracht uit:

    Install-Package Swashbuckle.AspNetCore -Version 6.6.2
    

• In het dialoogvenster NuGet-pakketten beheren:

  • Klik met de rechtermuisknop op het project in Solution Explorer>NuGet-pakketten beheren
  • Stel de pakketbron in op 'nuget.org'
  • Zorg ervoor dat de optie Voorlopige versie opnemen is ingeschakeld
  • Voer 'Swashbuckle.AspNetCore' in het zoekvak in
  • Selecteer het meest recente pakket 'Swashbuckle.AspNetCore' op het tabblad Bladeren en klik op Installeren

Visual Studio Code

Voer de volgende opdracht uit vanuit de Integrated Terminal:

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

.NET CLI

Voer de volgende opdracht uit:

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

Swagger middleware toevoegen en configureren

Voeg de Swagger-generator toe aan de servicesverzameling in Program.cs:

builder.Services.AddControllers();

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

De aanroep naar AddEndpointsApiExplorer in het voorgaande voorbeeld is alleen vereist voor minimale API's. Zie deze StackOverflow-postvoor meer informatie.

Schakel de middleware in voor het leveren van het gegenereerde JSON-document en de Swagger-gebruikersinterface, ook in Program.cs:

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

Met de voorgaande code wordt de Swagger middleware alleen toegevoegd als de huidige omgeving is ingesteld op Ontwikkeling. Met de UseSwaggerUI methodeaanroep wordt een ingesloten versie van het Swagger UI-hulpprogramma ingeschakeld.

Start de app en navigeer naar https://localhost:<port>/swagger/v1/swagger.json. Het gegenereerde document waarin de eindpunten worden beschreven, wordt weergegeven zoals wordt weergegeven in OpenAPI-specificatie (openapi.json).

De Swagger-gebruikersinterface vindt u op https://localhost:<port>/swagger. Verken de API via de Swagger-gebruikersinterface en neem deze op in andere programma's.

Aanbeveling

Als u de Swagger-gebruikersinterface wilt gebruiken in de hoofdmap van de app (https://localhost:<port>/), stelt u de eigenschap RoutePrefix in op een lege tekenreeks:

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

Als u mappen met IIS of een omgekeerde proxy gebruikt, stelt u het Swagger-eindpunt in op een relatief pad met behulp van het voorvoegsel ./. Bijvoorbeeld ./swagger/v1/swagger.json. Wanneer u /swagger/v1/swagger.json gebruikt, geeft de app instructies om het JSON-bestand op te zoeken in de werkelijke hoofdmap van de URL (plus het routevoorvoegsel, indien gebruikt). Gebruik bijvoorbeeld https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json in plaats van https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Notitie

Standaard genereert en maakt Swashbuckle Swagger JSON beschikbaar in versie 3.0 van de specificatie, officieel de OpenAPI-specificatie genoemd. Ter ondersteuning van compatibiliteit met eerdere versies kunt u ervoor kiezen om in plaats daarvan JSON beschikbaar te maken in de 2.0-indeling. Deze 2.0-indeling is belangrijk voor integraties zoals Microsoft Power Apps en Microsoft Flow die momenteel OpenAPI versie 2.0 ondersteunen. Als u wilt kiezen voor de 2.0-indeling, stelt u de eigenschap SerializeAsV2 in Program.csin:

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

Aanpassen en uitbreiden

Swagger biedt opties voor het documenteren van het objectmodel en het aanpassen van de gebruikersinterface zodat deze overeenkomt met uw thema.

API-informatie en -beschrijving

De configuratieactie die wordt doorgegeven aan de AddSwaggerGen-methode, voegt informatie toe, zoals de auteur, licentie en beschrijving.

Importeer in Program.csde volgende naamruimte om de klasse OpenApiInfo te gebruiken:

using Microsoft.OpenApi.Models;

Wijzig met behulp van de klasse OpenApiInfo de informatie die wordt weergegeven in de gebruikersinterface:

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

De Swagger-gebruikersinterface geeft de versiegegevens weer:

XML-opmerkingen

XML-opmerkingen kunnen worden ingeschakeld met de volgende benaderingen:

Visual Studio

• Klik met de rechtermuisknop op het project in Solution Explorer en selecteer Edit <project_name>.csproj.
• Voeg GenerateDocumentationFile toe aan het .csproj-bestand:

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

Visual Studio Code

Voeg GenerateDocumentationFile toe aan het .csproj-bestand:

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

.NET CLI

Voeg GenerateDocumentationFile toe aan het .csproj-bestand:

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

Het inschakelen van XML-opmerkingen biedt foutopsporingsinformatie voor niet-gedocumenteerde openbare typen en leden. Ongedocumenteerde typen en leden worden aangeduid door het waarschuwingsbericht. Het volgende bericht geeft bijvoorbeeld een schending van waarschuwingscode 1591 aan:

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

Als u waarschuwingen voor het hele project wilt onderdrukken, definieert u een door puntkomma's gescheiden lijst met waarschuwingscodes die in het projectbestand moeten worden genegeerd. Als u de waarschuwingscodes toevoegt aan $(NoWarn); worden de standaardwaarden van C# ook toegepast.

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

Als u alleen waarschuwingen voor specifieke leden wilt onderdrukken, plaatst u de code in #pragma waarschuwing preprocessorrichtlijnen. Deze methode is handig voor code die niet beschikbaar moet worden gesteld via de API-documenten. In het volgende voorbeeld wordt waarschuwingscode CS1591 genegeerd voor de hele TodoContext klasse. Het handhaven van de waarschuwingscode wordt hersteld aan het einde van de class-definitie. Geef meerdere waarschuwingscodes op met een door komma's gescheiden lijst.

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

Configureer Swagger om het XML-bestand te gebruiken dat is gegenereerd met de voorgaande instructies. Voor Linux- of niet-Windows-besturingssystemen kunnen bestandsnamen en paden hoofdlettergevoelig zijn. Een TodoApi.XML-bestand is bijvoorbeeld geldig in Windows, maar niet in 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));
});

In de voorgaande code wordt Reflectie- gebruikt om een XML-bestandsnaam te maken die overeenkomt met die van het web-API-project. De eigenschap AppContext.BaseDirectory wordt gebruikt om een pad naar het XML-bestand te maken. Sommige Swagger-functies (bijvoorbeeld schemata van invoerparameters of HTTP-methoden en antwoordcodes van de respectieve kenmerken) werken zonder gebruik te maken van een XML-documentatiebestand. Voor de meeste functies, namelijk methodesamenvattingen en beschrijvingen van parameters en antwoordcodes, is het gebruik van een XML-bestand verplicht.

Door drie slash-opmerkingen toe te voegen aan een actie, wordt de Swagger-gebruikersinterface verbeterd door de beschrijving toe te voegen aan de sectiekop. Voeg een <samenvatting> element toe boven de actie Delete:

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

In de Swagger-gebruikersinterface wordt de binnenste tekst van het <summary> element van de voorgaande code weergegeven:

De gebruikersinterface wordt aangestuurd door het gegenereerde JSON-schema:

"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"
        }
    }
},

Voeg een <opmerkingen> element toe aan de documentatie van de Create actiemethode. Het vormt een aanvulling op informatie die is opgegeven in het <summary> element en biedt een krachtigere Swagger-gebruikersinterface. De inhoud van het <remarks>-element kan bestaan uit tekst, JSON of 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);
}

Let op de verbeteringen in de gebruikersinterface met deze aanvullende opmerkingen:

Gegevensaantekeningen

Markeer het model met kenmerken, gevonden in de System.ComponentModel.DataAnnotations naamruimte, om de Swagger UI-onderdelen te helpen aan te sturen.

Voeg het kenmerk [Required] toe aan de eigenschap Name van de klasse 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; }
}

De aanwezigheid van dit kenmerk wijzigt het gedrag van de gebruikersinterface en wijzigt het onderliggende JSON-schema:

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

Voeg het kenmerk [Produces("application/json")] toe aan de API-controller. Het doel is om aan te geven dat de acties van de controller een antwoordinhoudstype van application/json-ondersteunen:

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

In het mediatype vervolgkeuzemenu wordt dit inhoudstype als standaard geselecteerd voor de GET-acties van de controller.

Naarmate het gebruik van gegevensaantekeningen in de web-API toeneemt, worden de helppagina's voor de gebruikersinterface en API meer beschrijvend en nuttiger.

Antwoordtypen beschrijven

Ontwikkelaars die een web-API gebruiken, houden zich het meest bezig met wat er wordt geretourneerd, met name antwoordtypen en foutcodes (indien niet standaard). De antwoordtypen en foutcodes worden aangeduid in de XML-opmerkingen en gegevensaantekeningen.

De Create-actie retourneert een HTTP 201-statuscode bij succes. Er wordt een HTTP 400-statuscode geretourneerd wanneer de geplaatste aanvraagbody null is. Zonder de juiste documentatie in de Swagger-gebruikersinterface mist de consument kennis van deze verwachte resultaten. Los dit probleem op door de gemarkeerde regels toe te voegen in het volgende voorbeeld:

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

De Swagger-gebruikersinterface documentert nu duidelijk de verwachte HTTP-antwoordcodes:

Conventies kunnen worden gebruikt als alternatief voor het expliciet decoreren van afzonderlijke acties met [ProducesResponseType]. Zie Web-API-conventies gebruikenvoor meer informatie.

Ter ondersteuning van de [ProducesResponseType] decoratie biedt het Swashbuckle.AspNetCore.Annotations pakket extensies om de metagegevens van het antwoord, het schema en de parameters in te schakelen en te verrijken.

De gebruikersinterface aanpassen

De standaardgebruikersinterface is zowel functioneel als presenteerbaar. API-documentatiepagina's moeten echter uw merk of thema vertegenwoordigen. Het brandingproces van de Swashbuckle-onderdelen vereist het toevoegen van resources voor het leveren van statische bestanden en het opzetten van de mapstructuur om die bestanden te hosten.

Statische bestands-middleware inschakelen:

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

Als u extra CSS-stylesheets wilt toevoegen, voegt u deze toe aan de map wwwroot en specificeert u het relatieve pad in de middlewareopties.

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

Aanvullende informatiebronnen

• voorbeeldcode weergeven of downloaden (hoe te downloaden)
• de ontwikkelaarservaring van een API verbeteren met Swagger-documentatie