OpenAPI-ondersteuning in ASP.NET Core API-apps

ASP.NET Core ondersteunt het genereren van OpenAPI-documenten in op controller gebaseerde en minimale API's-apps. De OpenAPI-specificatie is een programmeertaalagnostische standaard voor het documenteren van HTTP-API's. Deze standaard wordt ondersteund in ASP.NET Core-apps via een combinatie van ingebouwde API's en opensource-bibliotheken. Er zijn drie belangrijke aspecten voor OpenAPI-integratie in een toepassing:

• Informatie genereren over de eindpunten in de app.
• Verzamel de informatie in een indeling die overeenkomt met het OpenAPI-schema.
• Het gegenereerde OpenAPI-document weergeven via een visuele gebruikersinterface of een geserialiseerd bestand.

ASP.NET Core-apps bieden ingebouwde ondersteuning voor het genereren van informatie over eindpunten in een app via het Microsoft.AspNetCore.OpenApi pakket.

De volgende code wordt gegenereerd door de ASP.NET Core minimale web-API-sjabloon en maakt gebruik van 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);
}

In de eerder genoemde gemarkeerde code:

• AddOpenApi registreert services die vereist zijn voor het genereren van OpenAPI-documenten in de DI-container van de toepassing.
• MapOpenApi voegt een eindpunt toe aan de toepassing voor het weergeven van het OpenAPI-document dat in JSON is geserialiseerd. Het OpenAPI-eindpunt is beperkt tot de ontwikkelomgeving om het risico op het blootstellen van gevoelige informatie te minimaliseren en de beveiligingsproblemen in productie te verminderen.

Microsoft.AspNetCore.OpenApi NuGet-pakket

Het Microsoft.AspNetCore.OpenApi pakket biedt de volgende functies:

• Ondersteuning voor het genereren van OpenAPI-documenten tijdens runtime en het openen ervan via een eindpunt in de toepassing.
• Ondersteuning voor 'transformer'-API's waarmee het gegenereerde document kan worden gewijzigd.

Als u het pakket wilt gebruiken, voegt u het Microsoft.AspNetCore.OpenApi toe als een PackageReference aan een projectbestand:

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

Zie Microsoft.AspNetCore.OpenApi voor meer informatie over het pakket.

Microsoft.Extensions.ApiDescription.Server NuGet-pakket

Het Microsoft.Extensions.ApiDescription.Server pakket biedt ondersteuning voor het genereren van OpenAPI-documenten tijdens de build en het serialiseren ervan.

Als u wilt gebruiken Microsoft.Extensions.ApiDescription.Server, voegt u het toe als een PackageReference aan een projectbestand. Het genereren van documenten tijdens de build is ingeschakeld door de OpenApiGenerateDocuments eigenschap in te stellen. Het gegenereerde OpenAPI-document wordt standaard opgeslagen in de obj map, maar u kunt de uitvoermap aanpassen door de OpenApiDocumentsDirectory eigenschap in te stellen.

<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-bewerking v. API-eindpunt

In de volgende secties worden de verschillen uitgelegd tussen een API, een API-eindpunt en een API-bewerking in de context van ASP.NET Core- en OpenAPI-documentatie.

API (Application Programming Interface)

Een API is een set regels en protocollen voor het bouwen en communiceren met softwaretoepassingen. Hiermee wordt gedefinieerd hoe verschillende softwareonderdelen moeten communiceren. In het algemeen verwijst 'API' doorgaans naar een webservice die functionaliteit beschikbaar maakt via HTTP.

In ASP.NET Core wordt meestal een API gebouwd met behulp van controllers of minimale API's, die binnenkomende HTTP-aanvragen verwerken en antwoorden retourneren.

ASP.NET Core's interne naamconventies gebruiken soms 'API' anders. In API Explorer vertegenwoordigt een ApiDescription bijvoorbeeld een API-bewerking in plaats van de volledige API-service. Dit onderscheid weerspiegelt interne naamconventies en verschilt soms van de bredere definitie die hier wordt gebruikt.

Zie Inleiding tot apiExplorer in ASP.NET Core voor meer informatie over API Explorer.

API-bewerking

Een API-bewerking vertegenwoordigt een specifieke actie of mogelijkheid die een API biedt. In ASP.NET Core komt dit overeen met:

• Actiemethoden voor controller in MVC-api's
• Routeafhandelaars in minimale API's

Elke bewerking wordt gedefinieerd door de HTTP-methode (GET, POST, PUTenzovoort), het pad, de parameters en de antwoorden.

API-eindpunt

Een API-eindpunt is een specifieke URL:

• Dit vertegenwoordigt een specifieke resource of functionaliteit die beschikbaar wordt gesteld door de API.
• Biedt het exacte adres waarnaar een client een HTTP-aanvraag moet verzenden om te kunnen communiceren met een bepaalde API-bewerking.

Een eindpunt is een combinatie van de basis-URL van de API en een specifiek pad naar de gewenste resource, samen met de ondersteunde HTTP-methoden:

• Voor controller-gebonden API's combineren de API-eindpunten de route-sjabloon met de controller en actie.
• Voor minimale API's worden eindpunten expliciet gedefinieerd met app.MapGet(), app.MapPost()enzovoort.

Bijvoorbeeld het api/products/{id} eindpunt dat de volgende bewerkingen ondersteunt:

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

Eindpunten bevatten vaak queryparameters, bijvoorbeeld GET /api/products?category=electronics&sort=price

OpenAPI-documentatie

In de context van OpenAPI beschrijft de documentatie de API als geheel, inclusief alle eindpunten en bewerkingen. OpenAPI biedt een gestructureerde manier om API's te documenteren, zodat ontwikkelaars gemakkelijker kunnen begrijpen hoe ze ermee kunnen communiceren.

API-bewerkingen zijn de primaire focus van OpenAPI-documentatie. De OpenAPI-specificatie organiseert documentatie op bewerkingen, die zijn gegroepeerd op paden (eindpunten). Elke bewerking wordt beschreven met details zoals parameters, aanvraagteksten, antwoorden en meer. Met deze gestructureerde indeling kunnen hulpprogramma's clientbibliotheken, server-stubs en interactieve documentatie automatisch genereren.

In een OpenAPI-document:

• In het hele document wordt de API als geheel beschreven
• Elk pad item (zoals /api/products/{id}) vertegenwoordigt een eindpunt
• Onder elk pad worden de HTTP-methoden (GET, POST, PUT, enzovoort) gebruikt om de bewerkingen te definiëren.
• Elke bewerking bevat details over parameters, aanvraagbody, antwoorden, enzovoort.

Voorbeeld in OpenAPI JSON-indeling:

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": {...}
      }
    }
  }
}

Vergelijking van API-, API-bewerkingen en API-eindpunten

De volgende tabel bevat een overzicht van de verschillen tussen een API, een API-bewerking en een API-eindpunt:

ASP.NET Core OpenAPI-broncode op GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Aanvullende informatiebronnen

• Authenticatie en autorisatie in minimale API's

De OpenAPI-specificatie is een programmeertaalagnostische standaard voor het documenteren van HTTP-API's. Deze standaard wordt ondersteund in minimale API's via een combinatie van ingebouwde API's en opensourcebibliotheken. Er zijn drie belangrijke aspecten voor OpenAPI-integratie in een toepassing:

• Informatie genereren over de eindpunten in de app.
• Verzamel de informatie in een indeling die overeenkomt met het OpenAPI-schema.
• Het gegenereerde OpenAPI-schema weergeven via een visuele gebruikersinterface of een geserialiseerd bestand.

Minimale API's bieden ingebouwde ondersteuning voor het genereren van informatie over eindpunten in een app via het Microsoft.AspNetCore.OpenApi-pakket. Voor het beschikbaar maken van de gegenereerde OpenAPI-definitie via een visuele gebruikersinterface is een pakket van derden vereist.

Zie de .NET 9-versie van dit artikelvoor meer informatie over ondersteuning voor OpenAPI in op controller gebaseerde API's.