OpenAPI-támogatás ASP.NET Core API-alkalmazásokban

ASP.NET Core támogatja az OpenAPI-dokumentumok létrehozását vezérlőalapú és minimális API-alkalmazásokban. Az OpenAPI-specifikáció egy programozási nyelv-agnosztikus szabvány a HTTP API-k dokumentálására. Ezt a szabványt beépített API-k és nyílt forráskódú kódtárak kombinációjával ASP.NET Core-alkalmazások támogatják. Egy alkalmazás OpenAPI-integrációjának három fő aspektusa van:

• Az alkalmazás végpontjaival kapcsolatos információk generálása.
• Gyűjtse össze az adatokat az OpenAPI-sémának megfelelő formátumban.
• A létrehozott OpenAPI-dokumentum megjelenítése vizualizációs felhasználói felületen vagy szerializált fájlon keresztül.

ASP.NET Core-alkalmazások beépített támogatást nyújtanak az alkalmazások végpontjaival kapcsolatos információk csomagon keresztüli Microsoft.AspNetCore.OpenApi létrehozásához.

A következő kódot a ASP.NET Core minimális webes API-sablonja hozza létre, és OpenAPI-t használ:

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

Az előző kiemelt kódban:

• AddOpenApi regisztrálja az OpenAPI-dokumentumok létrehozásához szükséges szolgáltatásokat az alkalmazás DI-tárolójában.
• MapOpenApi Hozzáad egy végpontot az alkalmazáshoz az OpenAPI-dokumentum JSON-ba szerializált megtekintéséhez. Az OpenAPI-végpont a fejlesztési környezetre korlátozódik, hogy minimalizálja a bizalmas információk felfedésének kockázatát, és csökkentse az éles környezetben lévő biztonsági réseket.

Microsoft.AspNetCore.OpenApi NuGet-csomag

A Microsoft.AspNetCore.OpenApi csomag a következő funkciókat biztosítja:

• 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.

A Microsoft.AspNetCore.OpenApi csomag használatához adja hozzá PackageReferenceként egy projektfájlhoz:

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

A csomagról Microsoft.AspNetCore.OpenApi az OpenAPI-dokumentumok létrehozása című témakörben olvashat bővebben.

Microsoft.Extensions.ApiDescription.Server NuGet-csomag

A Microsoft.Extensions.ApiDescription.Server csomag támogatja az OpenAPI-dokumentumok létrehozását és szerializálását a létrehozáskor.

A használatához Microsoft.Extensions.ApiDescription.Serveradja hozzá PackageReference-ként egy projektfájlhoz. A dokumentumlétrehozás a létrehozáskor engedélyezve van a OpenApiGenerateDocuments tulajdonság beállításával. A létrehozott OpenAPI-dokumentum alapértelmezés szerint a obj könyvtárba lesz mentve, de a tulajdonság beállításával testre szabhatja a OpenApiDocumentsDirectory kimeneti könyvtárat.

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

API v. API-művelet v. API-végpont

Az alábbi szakaszok az API- és API-végpontok, valamint az API-műveletek közötti különbségeket ismertetik a ASP.NET Core és az OpenAPI dokumentációjának kontextusában.

API (Alkalmazásprogramozási felület)

Az API a szoftveralkalmazások létrehozásához és használatához szükséges szabályok és protokollok halmaza. Meghatározza, hogy a különböző szoftverösszetevők hogyan kommunikáljanak. Az "API" általában olyan webszolgáltatásra utal, amely HTTP-en keresztül teszi elérhetővé a funkciókat.

A ASP.NET Core-ban az API-k általában vezérlők vagy minimális API-k használatával épülnek fel, amelyek kezelik a bejövő HTTP-kéréseket, és válaszokat adnak vissza.

ASP.NET Core belső elnevezési konvenciói néha eltérően használják az "API"-t. Az API Explorerben például az "ApiDescription" valójában egy API-műveletet jelöl a teljes API-szolgáltatás helyett. Ez a különbség a belső elnevezési konvenciókra utal, és néha eltér az itt használt tágabb definíciótól.

Az API Explorerrel kapcsolatos további információkért tekintse meg a ASP.NET Core ApiExplorerjének bemutatása című témakört.

API-művelet

Az API-műveletek egy adott műveletet vagy képességet jelölnek, amelyet egy API biztosít. A ASP.NET Core-ban ez a következőnek felel meg:

• Vezérlőműveleti módszerek MVC-stílusú API-kban
• Útvonalkezelők minimális API-kban

Minden műveletet a HTTP-metódus (GET, stbPOSTPUT.), az elérési út, a paraméterek és a válaszok határoznak meg.

API-végpont

Az API-végpont egy adott URL-cím:

• Ez az API által közzétett adott erőforrást vagy funkciót jelöli.
• Megadja azt a címet, amelyre az ügyfélnek HTTP-kérést kell küldenie egy adott API-művelet kezeléséhez.

A végpont az API alap URL-címének és a kívánt erőforrás adott elérési útjának kombinációja a támogatott HTTP-módszerekkel együtt:

• Vezérlőalapú API-k esetén a végpontok kombinálják az útvonalsablont a vezérlővel és a művelettel.
• A minimális API-k esetében a végpontok explicit módon vannak definiálva app.MapGet(), app.MapPost()stb.

Például a api/products/{id} következő műveleteket támogató végpont:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

A végpontok gyakran tartalmaznak lekérdezési paramétereket, például GET /api/products?category=electronics&sort=price

Az OpenAPI dokumentációja

Az OpenAPI kontextusában a dokumentáció az API egészét írja le, beleértve az összes végpontot és műveletet. Az OpenAPI strukturált módot kínál az API-k dokumentálására, így a fejlesztők könnyebben megérthetik, hogyan használhatják őket.

Az API-műveletek az OpenAPI dokumentációjának elsődleges fókuszát képezik. Az OpenAPI-specifikáció a dokumentációt műveletek szerint szervezi, amelyek elérési utak (végpontok) szerint vannak csoportosítva. Minden műveletet olyan részletekkel ismertetünk, mint a paraméterek, a kérelemtörzsek, a válaszok és egyebek. Ez a strukturált formátum lehetővé teszi, hogy az eszközök automatikusan generáljanak ügyfélkódtárakat, kiszolgálói csonkokat és interaktív dokumentációt.

OpenAPI-dokumentumban:

• A teljes dokumentum az API egészét írja le
• Minden elérési útelem (például /api/products/{id}) egy végpontot jelöl
• Az egyes elérési utak alatt a HTTP-metódusok (GET, POSTstb PUT.) határozzák meg a műveleteket
• Minden művelet részletes adatokat tartalmaz a paraméterekről, a kérelem törzséről, a válaszokról stb.

Példa OpenAPI JSON formátumban:

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

API, API-művelet és API-végpontok összehasonlítása

Az alábbi táblázat az API, az API-művelet és az API-végpont közötti különbségeket foglalja össze:

Fogalom	API-művelet	API-végpont
Definíció	Egy API-művelet logikai leírása: metódus + elérési út + viselkedés	A kérelmeket figyelő tényleges konfigurált HTTP-útvonal
szint	Fogalmi, milyen művelet történhet	Konkrétan, milyen URL-cím és metódus van megfeleltetve
Hozzá van kötve	OpenAPI API-tervezés/specifikáció	ASP.NET Core-útválasztás futásidőben
Leírja	Az API feladata például a "termék létrehozása"	Hol és hogyan hívhatja meg például: POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
Az ASP.NET Core-ban	Vezérlőműveletek vagy minimális API-metódusok az útválasztás feloldása előtt	Futtatókörnyezetben feloldott végpontobjektumok

ASP.NET Core OpenAPI-forráskód a GitHubon

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

További források

• Hitelesítés és engedélyezés minimális API-kban