Podpora OpenAPI v minimálních aplikacích API
Poznámka:
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Upozorňující
Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Důležité
Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Specifikace OpenAPI je programovací standard nezávislý na jazyce pro dokumentaci rozhraní HTTP API. Tento standard se podporuje v minimálních rozhraních API prostřednictvím kombinace integrovaných rozhraní API a opensourcových knihoven. Integrace OpenAPI v aplikaci má tři klíčové aspekty:
- Generování informací okoncovýchch
- Shromažďování informací do formátu, který odpovídá schématu OpenAPI.
- Vystavení vygenerovaného schématu OpenAPI prostřednictvím vizuálního uživatelského rozhraní nebo serializovaného souboru
Minimální rozhraní API poskytují integrovanou podporu generování informací o koncových bodech v aplikaci prostřednictvím Microsoft.AspNetCore.OpenApi
balíčku.
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.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}
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");
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:
AddOpenApi
registruje služby potřebné pro generování dokumentů OpenAPI do kontejneru DI aplikace.MapOpenApi
přidá do aplikace koncový bod pro zobrazení dokumentu OpenAPI serializovaného do JSON.
Microsoft.AspNetCore.OpenApi
Balíček NuGet
Balíček Microsoft.AspNetCore.OpenApi
poskytuje funkce, které zahrnují následující funkce:
- Podpora generování dokumentů OpenAPI za běhu a přístup k nim prostřednictvím koncového bodu v aplikaci
- Podpora rozhraní API transformátoru, která umožňují úpravu vygenerovaného dokumentu
- Podpora generování dokumentů OpenAPI v době sestavení a jejich serializace na disk
Microsoft.AspNetCore.OpenApi
se přidá jako PackageReference do souboru projektu:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
</ItemGroup>
</Project>
Další informace o Microsoft.AspNetCore.OpenApi
balíčku najdete v tématu Začínáme s Microsoft.AspNetCore.OpenApi.
Popis koncových bodů
OpenAPI podporuje poskytování souhrnů a popisů tras registrovaných v aplikaci. Minimální rozhraní API podporují dvě strategie nastavení těchto vlastností na daném koncovém bodu pomocí následujících metod rozšíření a atributů:
- Souhrny: WithSummary
- Popisy: WithDescription
- Souhrny: EndpointSummaryAttribute
- Popisy: EndpointDescriptionAttribute
Následující ukázka ukazuje různé strategie nastavení souhrnů a popisů.
app.MapGet("/extension-methods", () => "Hello world!")
.WithSummary("This is a summary.")
.WithDescription("This is a description.");
app.MapGet("/attributes",
[EndpointSummary("This is a summary.")]
[EndpointDescription("This is a description.")]
() => "Hello world!");
Nastavení značek OpenAPI
OpenAPI podporuje zadávání značek v každém koncovém bodu jako formu kategorizace. Minimální rozhraní API podporují dvě strategie nastavení značek OpenAPI na daném koncovém bodu pomocí:
Následující ukázka ukazuje různé strategie nastavení značek.
app.MapGet("/extension-methods", () => "Hello world!")
.WithTags("todos", "projects");
app.MapGet("/attributes",
[Tags("todos", "projects")]
() => "Hello world!");
Vyloučení koncových bodů z vygenerovaného dokumentu
Ve výchozím nastavení jsou všechny koncové body definované v aplikaci zdokumentované ve vygenerovaném souboru OpenAPI. Minimální rozhraní API podporují dvě strategie vyloučení daného koncového bodu z dokumentu OpenAPI pomocí:
Následující ukázka ukazuje různé strategie vyloučení daného koncového bodu z vygenerovaného dokumentu OpenAPI.
app.MapGet("/extension-method", () => "Hello world!")
.ExcludeFromDescription();
app.MapGet("/attributes",
[ExcludeFromDescription]
() => "Hello world!");
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é mohou vrátit odpověď ProblemDetails, rozšiřující metodu ProducesProblem nebo TypedResults.Problem lze použít k přidání příslušné poznámky k metadatům koncového bodu.
Pokud některá z těchto strategií neposkytuje žádné explicitní poznámky, 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ěkolikIResult
konkré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čce 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/xml
obsahu .
app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
.Accepts<Todo>("application/xml");
Kromě Acceptsrozšiřující metody může typ parametru 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.
ASP.NET základní zdrojový kód OpenAPI na GitHubu
Další materiály
Specifikace OpenAPI je programovací standard nezávislý na jazyce pro dokumentaci rozhraní HTTP API. Tento standard se podporuje v minimálních rozhraních API prostřednictvím kombinace integrovaných rozhraní API a opensourcových knihoven. Integrace OpenAPI v aplikaci má tři klíčové aspekty:
- Generování informací okoncovýchch
- Shromažďování informací do formátu, který odpovídá schématu OpenAPI.
- Vystavení vygenerovaného schématu OpenAPI prostřednictvím vizuálního uživatelského rozhraní nebo serializovaného souboru
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.
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 zMicrosoft.AspNetCore.OpenApi
balíčku. UseSwagger
př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é mohou vrátit odpověď ProblemDetails, rozšiřující metodu ProducesProblem
nebo TypedResults.Problem
lze použít k přidání příslušné poznámky k metadatům koncového bodu.
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 aTypedResults
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ěkolikIResult
konkré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/xml
obsahu .
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 naFromBody
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
Další materiály
Aplikace může popsat specifikaci OpenAPI pro obslužné rutiny tras pomocí Swashbuckle.
Následující kód je typická aplikace ASP.NET Core s podporou OpenAPI:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
Version = "v1" });
});
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
$"{builder.Environment.ApplicationName} v1"));
}
app.MapGet("/swag", () => "Hello Swagger!");
app.Run();
Vyloučit popis OpenAPI
V následující ukázce /skipme
je koncový bod vyloučený z generování popisu OpenAPI:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}
app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
.ExcludeFromDescription();
app.Run();
Popis typů odpovědí
Následující příklad používá předdefinované typy výsledků k přizpůsobení odpovědi:
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);
Přidání ID operací do OpenAPI
app.MapGet("/todoitems2", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithName("GetToDoItems");
Přidání značek do popisu OpenAPI
Následující kód používá značku seskupení OpenAPI:
app.MapGet("/todoitems", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithTags("TodoGroup");
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro