OpenAPI-stöd i ASP.NET Core API-appar

ASP.NET Core stöder generering av OpenAPI-dokument i kontrollantbaserade och minimala API:er. OpenAPI-specifikationen är en programmeringsspråkagnostisk standard för att dokumentera HTTP-API:er. Den här standarden stöds i ASP.NET Core-appar genom en kombination av inbyggda API:er och bibliotek med öppen källkod. Det finns tre viktiga aspekter av OpenAPI-integrering i ett program:

• Generera information om slutpunkterna i appen.
• Samla in informationen i ett format som matchar OpenAPI-schemat.
• Exponera det genererade OpenAPI-dokumentet via ett visuellt användargränssnitt eller en serialiserad fil.

ASP.NET Core-appar ger inbyggt stöd för att generera information om slutpunkter i en app via Microsoft.AspNetCore.OpenApi paketet.

Följande kod genereras av ASP.NET Core minimal webb-API-mall och använder 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);
}

I föregående markerade kod:

• AddOpenApi registrerar tjänster som krävs för generering av OpenAPI-dokument i programmets DI-container.
• MapOpenApi lägger till en slutpunkt i programmet för att visa OpenAPI-dokumentet serialiserat i JSON. OpenAPI-slutpunkten är begränsad till utvecklingsmiljön för att minimera risken för att exponera känslig information och minska sårbarheterna i produktionen.

Microsoft.AspNetCore.OpenApi NuGet-paket

Paketet Microsoft.AspNetCore.OpenApi innehåller följande funktioner:

• Stöd för att generera OpenAPI-dokument under körningen och ge åtkomst till dem via en slutpunkt i applikationen.
• Stöd för "transformerings-API:er" som gör det möjligt att ändra det genererade dokumentet.

Om du vill använda Microsoft.AspNetCore.OpenApi paketet lägger du till det som en PackageReference i en projektfil:

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

Mer information om paketet finns i Microsoft.AspNetCore.OpenApiGenerera OpenAPI-dokument.

Microsoft.Extensions.ApiDescription.Server NuGet-paket

Paketet Microsoft.Extensions.ApiDescription.Server ger stöd för att generera OpenAPI-dokument vid byggtiden och serialisera dem.

Om du vill använda Microsoft.Extensions.ApiDescription.Serverlägger du till den som en PackageReference i en projektfil. Dokumentgenerering vid kompileringstillfället aktiveras genom att ange egenskapen OpenApiGenerateDocuments . Som standard sparas det genererade OpenAPI-dokumentet i obj katalogen, men du kan anpassa utdatakatalogen genom att ange OpenApiDocumentsDirectory egenskapen.

<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-åtgärd v. API-slutpunkt

I följande avsnitt förklaras skillnaderna mellan ett API, en API-slutpunkt och en API-åtgärd i samband med ASP.NET Core- och OpenAPI-dokumentation.

API (Application Programming Interface)

Ett API är en uppsättning regler och protokoll för att skapa och interagera med program. Den definierar hur olika programvarukomponenter ska kommunicera. I allmän webbutveckling refererar "API" vanligtvis till en webbtjänst som exponerar funktioner via HTTP.

I ASP.NET Core skapas vanligtvis ett API med hjälp av kontrollanter eller minimala API:er, som hanterar inkommande HTTP-begäranden och returnerar svar.

ASP.NET Cores interna namngivningskonventioner använder ibland "API" på olika sätt. I API Explorer representerar till exempel en "ApiDescription" faktiskt en API-åtgärd i stället för den fullständiga API-tjänsten. Den här skillnaden återspeglar interna namngivningskonventioner och skiljer sig ibland från den bredare definition som används här.

Mer information om API Explorer finns i Introduktion till ApiExplorer i ASP.NET Core .

API-åtgärd

En API-åtgärd representerar en specifik åtgärd eller funktion som ett API tillhandahåller. I ASP.NET Core motsvarar detta:

• Kontrollantåtgärdsmetoder i API:er i MVC-format
• Routningshanterare i minimala API:er

Varje åtgärd definieras av dess HTTP-metod (GET, POST, PUT, osv.), sökväg, parametrar och svar.

API-slutpunkt

En API-slutpunkt är en specifik URL:

• Det representerar en specifik resurs eller funktion som exponeras av API:et.
• Anger den exakta adress som en klient behöver skicka en HTTP-begäran till för att interagera med en viss API-åtgärd.

En slutpunkt är en kombination av API:ets bas-URL och en specifik sökväg till den önskade resursen, tillsammans med de HTTP-metoder som stöds:

• För kontrollantbaserade API:er kombinerar slutpunkter routningsmallen med kontrollant och åtgärd.
• För minimala API:er definieras slutpunkter uttryckligen med app.MapGet(), app.MapPost()osv.

Till exempel slutpunkten api/products/{id} som stöder följande åtgärder:

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

Slutpunkter innehåller ofta frågeparametrar, till exempel GET /api/products?category=electronics&sort=price

OpenAPI-dokumentation

I samband med OpenAPI beskriver dokumentationen API:et som helhet, inklusive alla dess slutpunkter och åtgärder. OpenAPI är ett strukturerat sätt att dokumentera API:er, vilket gör det enklare för utvecklare att förstå hur de interagerar med dem.

API-åtgärder är det primära fokuset i OpenAPI-dokumentationen. OpenAPI-specifikationen organiserar dokumentationen efter åtgärder, som grupperas efter sökvägar (slutpunkter). Varje åtgärd beskrivs med information som parametrar, begärandeorgan, svar med mera. Det här strukturerade formatet gör att verktyg kan generera klientbibliotek, serverstubbar och interaktiv dokumentation automatiskt.

I ett OpenAPI-dokument:

• Hela dokumentet beskriver API:et som helhet
• Varje sökvägsobjekt (till exempel /api/products/{id}) representerar en slutpunkt
• Under varje sökväg definierar HTTP-metoderna (GET, POST, PUTosv.) åtgärderna
• Varje åtgärd innehåller information om parametrar, begärandetext, svar osv.

Exempel i OpenAPI JSON-format:

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-åtgärd och API-slutpunktsjämförelse

I följande tabell sammanfattas skillnaderna mellan ett API, en API-åtgärd och en API-slutpunkt:

ASP.NET Core OpenAPI-källkod på GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Ytterligare resurser

• autentisering och auktorisering i minimala API:er

OpenAPI-specifikationen är en programmeringsspråkagnostisk standard för att dokumentera HTTP-API:er. Den här standarden stöds i minimala API:er genom en kombination av inbyggda API:er och bibliotek med öppen källkod. Det finns tre viktiga aspekter av OpenAPI-integrering i ett program:

• Generera information om slutpunkterna i appen.
• Samla in informationen i ett format som matchar OpenAPI-schemat.
• Exponera det genererade OpenAPI-schemat via ett visuellt användargränssnitt eller en serialiserad fil.

Minimala API:er ger inbyggt stöd för att generera information om slutpunkter i en app via Microsoft.AspNetCore.OpenApi-paketet. För att exponera den genererade OpenAPI-definitionen via ett visuellt användargränssnitt krävs ett paket från tredje part.

Information om stöd för OpenAPI i kontrollantbaserade API:er finns i .NET 9-versionen av den här artikeln.