OpenAPI-dokumentumok létrehozása

A Microsoft.AspNetCore.OpenApi csomag beépített támogatást nyújt az OpenAPI-dokumentumkészítéshez a ASP.NET Core-ban. A csomag a következő funkciókat biztosítja:

• OpenAPI 3.1-es verziójú dokumentumok létrehozásának támogatása.
• A JSON-séma 2020–2012-ben készült vázlatának támogatása.
• OpenAPI-dokumentumok futásidőben történő létrehozásának és az alkalmazás végpontján keresztüli elérésének támogatása.
• Az "átalakító" API-k támogatása, amelyek lehetővé teszik a létrehozott dokumentum módosítását.
• Több OpenAPI-dokumentum egyetlen alkalmazásból történő létrehozásának támogatása.
• Kihasználja a System.Text.Jsonáltal biztosított JSON-sématámogatást.
• Kompatibilis a natív AoT-vel.

A létrehozott dokumentumok alapértelmezett OpenAPI-verziója a 3.1. A verzió módosítható azáltal, hogy explicit módon beállítjuk a OpenApiVersionOpenApiOptions delegált paraméterének configureOptionsAddOpenApi tulajdonságát.

builder.Services.AddOpenApi(options =>
{
    // Specify the OpenAPI version to use
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

Az OpenAPI dokumentum generálásakor összeállítási időben az OpenAPI verzió a --openapi-version MSBuild elemben található OpenApiGenerateDocumentsOptions beállításával választható ki.

<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document -->
<OpenApiGenerateDocumentsOptions>
  --openapi-version OpenApi3_1
</OpenApiGenerateDocumentsOptions>

Csomag telepítése

Telepítse a Microsoft.AspNetCore.OpenApi csomagot:

Visual Studio

A következő parancsot a Package Manager Konzol-ból futtassa:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Futtassa a következő parancsot az alkalmazás projektfájlját tartalmazó könyvtárba megnyitott parancshéjban:

dotnet add package Microsoft.AspNetCore.OpenApi

OpenAPI-dokumentumlétrehozás konfigurálása

A következő kód:

• OpenAPI-szolgáltatásokat ad hozzá az alkalmazásszerkesztő szolgáltatásgyűjteményének AddOpenApi bővítménymetódusával.
• Leképzi az OpenAPI-dokumentum JSON formátumban való megtekintésére szolgáló végpontot az alkalmazás MapOpenApi bővítménymetódusával.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Indítsa el az alkalmazást, és haladjon a https://localhost:{port}/openapi/v1.json felé a létrehozott OpenAPI-dokumentum megtekintéséhez, ahol a {port} helyőrző a port.

Az OpenAPI-dokumentumok létrehozásának testreszabása

Az alábbi szakaszok bemutatják, hogyan szabhatja testre az OpenAPI-dokumentumok létrehozását.

OpenAPI-dokumentum létrehozása YAML formátumban

Az OpenAPI-dokumentum JSON vagy YAML formátumban is létrehozható. Alapértelmezés szerint az OpenAPI-dokumentum JSON formátumban jön létre. Az OpenAPI-dokumentum YAML formátumban való létrehozásához adja meg a MapOpenApi hívás végpontját egy ".yaml" vagy ".yml" utótaggal, ahogyan az alábbi példában látható, ahol a {documentName} helyőrző a dokumentum neve:

app.MapOpenApi("/openapi/{documentName}.yaml");

Az OpenAPI-dokumentumok yaML formátumban történő létrehozása nem támogatott, de jövőbeli előzetes verzióra tervezett.

Az OpenAPI-dokumentum nevének testreszabása

Az alkalmazás minden OpenAPI-dokumentumának egyedi neve van. A regisztrált alapértelmezett dokumentumnév a következő v1:

builder.Services.AddOpenApi(); // Document name is v1

A dokumentum neve úgy módosítható, hogy paraméterként adja át a nevet a AddOpenApi hívásnak:

builder.Services.AddOpenApi("internal"); // Document name is internal

A dokumentum neve több helyen is megjelenik az OpenAPI-implementációban.

A létrehozott OpenAPI-dokumentum lekérésekor a rendszer a dokumentum nevét adja meg a kérelem documentName paraméterargumentumaként. Az alábbi kérések feloldják a v1 és internal dokumentumokat.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Létrehozott dokumentum OpenAPI-verziójának testreszabása

Az OpenAPI-dokumentum létrehozása alapértelmezés szerint létrehoz egy, az OpenAPI-specifikációnak megfelelő dokumentumot. Az alábbi kód bemutatja, hogyan módosíthatja az OpenAPI-dokumentum alapértelmezett verzióját:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});

Az OpenAPI-végpont útvonalának testreszabása

Alapértelmezés szerint a MapOpenApi hívással regisztrált OpenAPI-végpont a /openapi/{documentName}.json végponton teszi elérhetővé a dokumentumot. Az alábbi kód bemutatja, hogyan szabhatja testre azt az útvonalat, amelyen az OpenAPI-dokumentum regisztrálva van:

app.MapOpenApi("/openapi/{documentName}/openapi.json");

Lehetséges, de nem ajánlott eltávolítani a documentName útvonalparamétert a végpontútvonalról. Amikor a documentName útvonalparaméter el lesz távolítva a végpontútvonalról, a keretrendszer megpróbálja feloldani a dokumentum nevét a lekérdezési paraméterből. Ha nem adja meg a documentName sem az útvonalban, sem a lekérdezésben, az váratlan viselkedést eredményezhet.

Az OpenAPI-végpont testreszabása

Mivel az OpenAPI-dokumentumot egy útvonalkezelő végponton keresztül kézbesítik, a standard minimális végpontok számára elérhető testreszabások az OpenAPI-végpont számára érhetők el.

OpenAPI-dokumentumhozzáférés korlátozása jogosult felhasználók számára

Az OpenAPI-végpont alapértelmezés szerint nem engedélyezi az engedélyezési ellenőrzéseket. Az engedélyezési ellenőrzések azonban alkalmazhatók az OpenAPI-dokumentumra. A következő kódban az OpenAPI-dokumentumhoz való hozzáférés a szerepkörrel rendelkező tester felhasználókra korlátozódik:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

Gyorsítótárazott OpenAPI-dokumentum

Az OpenAPI-dokumentum minden alkalommal újra létrejön, amikor a rendszer kérést küld az OpenAPI-végpontnak. A regeneráció lehetővé teszi, hogy a transzformátorok dinamikus alkalmazásállapotokat építsenek be a működésükbe. Például egy kérés újragenerálása a HTTP-környezet részleteivel. Adott esetben az OpenAPI-dokumentum gyorsítótárazható, hogy ne hajtsa végre a dokumentumlétrehozási folyamatot minden HTTP-kérésen.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi()
        .CacheOutput();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Több OpenAPI-dokumentum létrehozása

Bizonyos esetekben hasznos lehet több OpenAPI-dokumentum létrehozása egyetlen ASP.NET Core API-alkalmazástól eltérő tartalommal. Ilyen forgatókönyvek például az OpenAPI-dokumentáció létrehozása különböző esetekben:

• Célközönségek, például nyilvános és belső API-k.
• API-k verziói.
• Az alkalmazás részei, például egy előtér- és háttér API.

Több OpenAPI-dokumentum létrehozásához minden dokumentumhoz egyszer hívja meg a AddOpenApi bővítménymetódust, és minden alkalommal adjon meg egy másik dokumentumnevet az első paraméterben.

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Minden egyes meghívás AddOpenApi megadhatja a saját beállításkészletét, így minden OpenAPI-dokumentumhoz ugyanazt vagy különböző testreszabást használhatja.

A keretrendszer a ShouldIncludeOpenApiOptions delegálási módszerét használja annak meghatározására, hogy mely végpontokat vegye fel az egyes dokumentumokba.

Minden dokumentum esetében a ShouldInclude delegálási metódust hívja meg az alkalmazás minden végpontja, és átadja a végpont ApiDescription objektumát. A metódus logikai értéket ad vissza, amely jelzi, hogy a végpont szerepeljen-e a dokumentumban. Az ApiDescription objektum:

• Információkat tartalmaz a végpontról, például a HTTP-metódusról, az útvonalról és a választípusokról.
• A végponthoz attribútumokkal vagy kiterjesztési metódusokkal csatolt metaadatok.

A delegátus alapértelmezett implementációja a GroupNameApiDescription mezőjét használja. A delegált egy végponton van beállítva a WithGroupName bővítménymetódus vagy a EndpointGroupNameAttribute attribútum használatával. WithGroupName vagy a EndpointGroupName attribútum határozza meg, hogy mely végpontok szerepeljenek a dokumentumban. A csoportnévvel nem rendelkező végpontok szerepelnek az összes OpenAPI-dokumentumban.

// Include endpoints without a group name or with a group name
// that matches the document name
ShouldInclude = (description) => description.GroupName == null || 
    description.GroupName == DocumentName;    

A delegálási ShouldInclude metódust testre szabhatja úgy, hogy a végpontokat bármilyen feltétel alapján belefoglalja vagy kizárja.

OpenAPI-dokumentumok létrehozása a létrehozáskor

A tipikus webalkalmazásokban az OpenAPI-dokumentumok futásidőben jönnek létre, és egy HTTP-kérésen keresztül kézbesítik az alkalmazáskiszolgálónak.

Bizonyos esetekben hasznos az OpenAPI-dokumentum létrehozása az alkalmazás buildelési lépése során. Ilyen forgatókönyvek például az OpenAPI-dokumentáció létrehozása, amely a következő:

• Berögzítve a verziókezelésbe.
• Spec-alapú integrációs teszteléshez használatos.
• Statikusan kiszolgálva a webkiszolgálóról.

Ha támogatni szeretné az OpenAPI-dokumentumok létrehozását a létrehozáskor, telepítse a Microsoft.Extensions.ApiDescription.Server csomagot:

Visual Studio

A következő parancsot a Package Manager Konzol-ból futtassa:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

Futtassa a következő parancsot az alkalmazás projektfájlját tartalmazó könyvtárba megnyitott parancshéjban:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Telepítéskor ez a csomag:

• Automatikusan létrehozza az alkalmazáshoz társított Open API-dokumentumokat a buildelés során.
• Kitölti az Open API-dokumentumokat az alkalmazás kimeneti könyvtárában.

Ha több dokumentum van regisztrálva és a dokumentum neve nem szerepelv1, a projekt neve utótagként lesz hozzáadva a dokumentum nevével. Példa: {ProjectName}_{DocumentName}.json. A {ProjectName} helyőrző a projekt neve, a {DocumentName} helyőrző pedig a dokumentum neve.

Visual Studio Code

dotnet build
type obj\{ProjectName}.json

.NET CLI

dotnet build
cat obj/{ProjectName}.json

Build-time OpenAPI-naplók megtekintése (Terminálnaplózó)

A Microsoft.Extensions.ApiDescription.Server lépés GetDocument futtatásakor a dotnet build folyamatjelző üzenetek nem láthatók a .NET-terminálnaplózóval alapértelmezett részletességgel a .NET 8-as vagy újabb verziójában. Ezeknek az üzeneteknek az összeállítás során való felszínre hozásához használja az alábbi lehetőségek egyikét a dotnet build paranccsal.

A Terminálnaplózó részletességét állítsa be a -tlp opció v=d értékére (részletesség = részletes)

dotnet build -tlp:v=d

Tiltsa le a Terminálnaplózót, és használja az örökölt típusú naplókat a --tl következő beállítássaloff:

dotnet build --tl:off

Buildelési idő dokumentumgenerálásának testreszabása

A létrehozott Open API-fájl kimeneti könyvtárának módosítása

Alapértelmezés szerint a létrehozott OpenAPI-dokumentum ki lesz bocsátva az alkalmazás kimeneti könyvtárába. A kibocsátott fájl helyének módosításához állítsa be a cél elérési útját a OpenApiDocumentsDirectory tulajdonságban:

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
</PropertyGroup>

A OpenApiDocumentsDirectory értéke a projektfájlhoz képest határozható meg. . Az előző példában látható érték használatával az OpenAPI-dokumentumot ugyanabban a könyvtárban bocsátja ki, mint a projektfájl.

A kimeneti fájl nevének módosítása

Alapértelmezés szerint a létrehozott OpenAPI-dokumentum neve megegyezik az alkalmazás projektfájljával. A kibocsátott fájl nevének módosításához állítsa be az --file-name argumentumot a OpenApiGenerateDocumentsOptions tulajdonságban:

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>
    --file-name my-open-api
  </OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Válassza ki a létrehozandó OpenAPI-dokumentumot

Egyes alkalmazások több OpenAPI-dokumentum kibocsátására is konfigurálhatók. Több OpenAPI-dokumentum is létrehozható egy API különböző verzióihoz, illetve a nyilvános és a belső API-k megkülönböztetéséhez. Alapértelmezés szerint a buildelési idő dokumentumgenerátora az alkalmazásban konfigurált összes dokumentum fájljait bocsátja ki. Ha csak egyetlen dokumentumnevet szeretne kibocsátani, állítsa be az --document-name argumentumot a OpenApiGenerateDocumentsOptions tulajdonságban:

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>
    --document-name v2
  </OpenApiGenerateDocumentsOptions>
</PropertyGroup>

A futási környezet viselkedésének testreszabása a buildidőben történő dokumentumgenerálás során

A buildelési idejű OpenAPI-dokumentumlétrehozási funkciók az alkalmazások belépési pontjának egy makettkiszolgáló-implementációval történő elindításával működnek. A modellkiszolgálóknak pontos OpenAPI-dokumentumokat kell létrehozniuk, mert az OpenAPI-dokumentum összes információja nem elemezhető statikusan. Mivel a rendszer meghívja az alkalmazások belépési pontját, a rendszer meghívja az alkalmazások indítási logikáját. Ez magában foglalja azt a kódot, amely szolgáltatásokat injektál a DI tárolóba vagy olvas be konfigurációból. Bizonyos esetekben korlátozni kell a kódútvonalakat, amikor az alkalmazás belépési pontját buildidőben történő dokumentumgenerálásból hívják meg. Ezek a forgatókönyvek a következők:

• Nem olvassa a bizonyos konfigurációs karakterláncokat.
• Nem regisztrál adatbázissal kapcsolatos szolgáltatásokat.

Annak érdekében, hogy a build idején történő generálási folyamat korlátozza ezen kódútvonalak meghívását, feltételekhez köthetők az entry assembly ellenőrzése alapján.

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
    builder.AddServiceDefaults();
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults Olyan gyakori Aspire szolgáltatásokat ad hozzá, mint a szolgáltatásfelderítés, a rugalmasság, az állapotellenőrzések és az OpenTelemetria.

Vágás és natív AOT futtatás

Az OpenAPI a ASP.NET Core-ban támogatja a vágást és a natív AOT-t. Az alábbi lépések egy OpenAPI-alkalmazást hoznak létre és tesznek közzé vágással és natív AOT-val.

Hozzon létre egy új ASP.NET Core Web API-projektet (natív AOT):

dotnet new webapiaot

Az alkalmazás közzététele:

dotnet publish