Generování dokumentů OpenAPI

Minimální rozhraní API poskytují integrovanou podporu generování informací o koncových bodech v aplikaci prostřednictvím Microsoft.AspNetCore.OpenApi balíčku. Zveřejnění vygenerované definice OpenAPI prostřednictvím vizuálního uživatelského rozhraní vyžaduje balíček třetí strany. Informace o podpoře rozhraní OPENAPI v rozhraních API založených na kontroleru najdete ve verzi tohoto článku v .NET 9.

Následující kód vygeneruje ASP.NET minimální šablona webového rozhraní API a používá OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

V předchozím zvýrazněném kódu:

• Microsoft.AspNetCore.OpenApi je vysvětleno v další části.
• AddEndpointsApiExplorer : Nakonfiguruje aplikaci tak, aby používala Průzkumníka rozhraní API ke zjišťování a popisu koncových bodů s výchozími poznámkami. WithOpenApi přepisuje porovnávání výchozích poznámek vygenerovaných Průzkumníkem rozhraní API s poznámkami vytvořenými z Microsoft.AspNetCore.OpenApi balíčku.
• UseSwaggerpřidá middleware Swaggeru.
• UseSwaggerUI umožňuje vloženou verzi nástroje Swagger UI.
• WithName: Koncový IEndpointNameMetadata bod se používá pro generování propojení a považuje se za ID operace ve specifikaci OpenAPI daného koncového bodu.
• WithOpenApi je vysvětleno dále v tomto článku.

Microsoft.AspNetCore.OpenApi Balíček NuGet

ASP.NET Core poskytuje Microsoft.AspNetCore.OpenApi balíček pro interakci se specifikacemi OpenAPI pro koncové body. Balíček funguje jako propojení mezi modely OpenAPI definovanými v Microsoft.AspNetCore.OpenApi balíčku a koncovými body definovanými v minimálních rozhraních API. Balíček poskytuje rozhraní API, které zkoumá parametry koncového bodu, odpovědi a metadata a vytváří typ anotace OpenAPI, který se používá k popisu koncového bodu.

Microsoft.AspNetCore.OpenApi se přidá jako PackageReference do souboru projektu:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Při použití Swashbuckle.AspNetCore s Microsoft.AspNetCore.OpenApi, Swashbuckle.AspNetCore 6.4.0 nebo novější musí být použita. Microsoft.OpenApi 1.4.3 nebo novější se musí použít k využití konstruktorů kopírování při WithOpenApi vyvolání.

Přidání poznámek OpenAPI ke koncovým bodům prostřednictvím WithOpenApi

Volání WithOpenApi koncového bodu se přidá do metadat koncového bodu. Tato metadata můžou být následující:

• Spotřebované v balíčcích třetích stran, jako je Swashbuckle.AspNetCore.
• Zobrazí se v uživatelském rozhraní Swagger nebo ve vygenerovaném YAML nebo JSON pro definování rozhraní API.

app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();

Úprava poznámky OpenAPI v WithOpenApi

Metoda WithOpenApi přijímá funkci, kterou lze použít k úpravě anotace OpenAPI. Například v následujícím kódu se k prvnímu parametru koncového bodu přidá popis:

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

Přidání ID operací do OpenAPI

ID operací se používají k jednoznačné identifikaci daného koncového bodu v OpenAPI. Metodu WithName rozšíření lze použít k nastavení ID operace použité pro metodu.

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Alternativně OperationId lze vlastnost nastavit přímo na anotaci OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

Přidání značek do popisu OpenAPI

OpenAPI podporuje kategorizaci operací pomocí objektů značek. Tyto značky se obvykle používají k seskupení operací v uživatelském rozhraní Swaggeru. Tyto značky lze do operace přidat vyvoláním metody rozšíření WithTags na koncovém bodu s požadovanými značkami.

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

Případně můžete seznam OpenApiTags nastavit na anotaci OpenAPI prostřednictvím WithOpenApi metody rozšíření.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

Přidání souhrnu nebo popisu koncového bodu

Souhrn a popis koncového WithOpenApi bodu můžete přidat vyvoláním metody rozšíření. V následujícím kódu jsou souhrny nastavené přímo na anotaci OpenAPI.

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

Vyloučit popis OpenAPI

V následující ukázce /skipme je koncový bod vyloučený z generování popisu OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.UseHttpsRedirection();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Označení rozhraní API jako zastaralé

Pokud chcete koncový bod označit jako zastaralý, nastavte Deprecated vlastnost v poznámce OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

Popis typů odpovědí

OpenAPI podporuje zadání popisu odpovědí vrácených z rozhraní API. Minimální rozhraní API podporují tři strategie nastavení typu odpovědi koncového bodu:

• Produces Prostřednictvím metody rozšíření na koncovém bodu
• Prostřednictvím atributu ProducesResponseType v obslužné rutině trasy
• TypedResults Vrácením z obslužné rutiny trasy

Metodu Produces rozšíření lze použít k přidání Produces metadat do koncového bodu. Pokud nejsou zadány žádné parametry, metoda rozšíření naplní metadata pro cílový typ pod stavovým kódem 200 a typem application/json obsahu.

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

Použití TypedResults v implementaci obslužné rutiny trasy koncového bodu automaticky zahrnuje metadata typu odpovědi pro koncový bod. Například následující kód automaticky anotuje koncový bod odpovědí pod 200 stavovým kódem s typem application/json obsahu.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

Nastavení odpovědí pro ProblemDetails

Při nastavování typu odpovědi pro koncové body, které můžou vrátit odpověď ProblemDetails, metodu ProducesProblem ProducesValidationProblemrozšíření nebo TypedResults.Problem lze použít k přidání příslušné poznámky k metadatům koncového bodu. Všimněte si, že ProducesProblem metody a ProducesValidationProblem metody rozšíření nelze použít se skupinami tras v .NET 8 a starších verzích.

Pokud neexistují žádné explicitní poznámky poskytované některou z výše uvedených strategií, architektura se pokusí určit výchozí typ odpovědi prozkoumáním podpisu odpovědi. Tato výchozí odpověď se vyplní pod stavový 200 kód v definici OpenAPI.

Více typů odpovědí

Pokud koncový bod může v různých scénářích vracet různé typy odpovědí, můžete zadat metadata následujícími způsoby:

• Volejte metodu Produces rozšíření několikrát, jak je znázorněno v následujícím příkladu:

  app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
           await db.Todos.FindAsync(id) 
           is Todo todo
           ? Results.Ok(todo) 
           : Results.NotFound())
     .Produces<Todo>(StatusCodes.Status200OK)
     .Produces(StatusCodes.Status404NotFound);
  

• Použijte Results<TResult1,TResult2,TResultN> v podpisu a TypedResults v textu obslužné rutiny, jak je znázorněno v následujícím příkladu:

  app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
  {
      return bookList.FirstOrDefault((i) => i.Id == id) is Book book
       ? TypedResults.Ok(book)
       : TypedResults.NotFound();
  });
  

  Typy Results<TResult1,TResult2,TResultN> sjednocení deklarují, že obslužná rutina trasy vrací několik IResultkonkrétních typů a jakýkoli z těchto typů, které implementují IEndpointMetadataProvider , přispívají k metadatům koncového bodu.

  Typy sjednocení implementují implicitní operátory přetypování. Tyto operátory umožňují kompilátoru automaticky převést typy zadané v obecných argumentech na instanci sjednocovacího typu. Tato funkce má přidanou výhodu poskytování kontroly času kompilace, že obslužná rutina trasy vrací pouze výsledky, které deklaruje. Pokus o vrácení typu, který není deklarován jako jeden z obecných argumentů, aby výsledkem Results<TResult1,TResult2,TResultN> byla chyba kompilace.

Popis textu a parametrů požadavku

Kromě popisu typů vrácených koncovým bodem podporuje OpenAPI také přidávání poznámek ke vstupům spotřebovaným rozhraním API. Tyto vstupy spadají do dvou kategorií:

• Parametry, které se zobrazují v cestě, řetězci dotazu, hlavičkách nebo cookies
• Data přenášená jako součást textu požadavku

Architektura odvodí typy parametrů požadavku v cestě, dotazu a řetězci hlavičky automaticky na základě podpisu obslužné rutiny trasy.

Chcete-li definovat typ vstupů přenášených jako tělo požadavku, nakonfigurujte vlastnosti pomocí Accepts rozšiřující metody k definování typu objektu a typu obsahu, které jsou očekávány obslužnou rutinou požadavku. V následujícím příkladu koncový bod přijímá Todo objekt v textu požadavku s očekávaným typem application/xmlobsahu .

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Kromě rozšiřující metody může typ parametru Accepts popsat vlastní poznámku IEndpointParameterMetadataProvider implementací rozhraní. Následující typ například Todo přidá poznámku, která vyžaduje text požadavku s typem application/xml obsahu.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

Pokud není zadána žádná explicitní poznámka, architektura se pokusí určit výchozí typ požadavku, pokud je v obslužné rutině koncového bodu parametr textu požadavku. Odvození používá k vytvoření poznámky následující heuristiku:

• Parametry textu požadavku, které se čtou z formuláře prostřednictvím atributu [FromForm] , jsou popsány pomocí multipart/form-data typu obsahu.
• Všechny ostatní parametry textu požadavku jsou popsány pomocí application/json typu obsahu.
• Tělo požadavku je považováno za volitelné, pokud je nullable nebo pokud AllowEmpty je vlastnost nastavena na FromBody atribut.

Podpora správy verzí rozhraní API

Minimální rozhraní API podporují správu verzí rozhraní API prostřednictvím balíčku Asp.Versioning.Http. Příklady konfigurace správy verzí s minimálními rozhraními API najdete v úložišti správy verzí rozhraní API.

ASP.NET základní zdrojový kód OpenAPI na GitHubu

• WithOpenApi
• OpenApiGenerator

Další materiály

• Ověřování a autorizace v minimálních rozhraních API