Dukungan OpenAPI di aplikasi ASP.NET Core API

ASP.NET Core mendukung pembuatan dokumen OpenAPI di aplikasi API berbasis pengontrol dan minimal. Spesifikasi OpenAPI adalah standar bahasa-agnostik pemrograman untuk mendokumen API HTTP. Standar ini didukung di aplikasi ASP.NET Core melalui kombinasi API bawaan dan pustaka sumber terbuka. Ada tiga aspek utama untuk integrasi OpenAPI dalam aplikasi:

• Menghasilkan informasi tentang titik akhir di aplikasi.
• Mengumpulkan informasi ke dalam format yang cocok dengan skema OpenAPI.
• Mengekspos dokumen OpenAPI yang dihasilkan melalui UI visual atau file berseri.

ASP.NET Core menyediakan dukungan bawaan untuk menghasilkan informasi tentang titik akhir di aplikasi melalui Microsoft.AspNetCore.OpenApi paket.

Kode berikut dihasilkan oleh templat API web minimal ASP.NET Core dan menggunakan 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);
}

Dalam kode yang disorot sebelumnya:

• AddOpenApi mendaftarkan layanan yang diperlukan untuk pembuatan dokumen OpenAPI ke dalam kontainer DI aplikasi.
• MapOpenApi menambahkan titik akhir ke dalam aplikasi untuk melihat dokumen OpenAPI yang diserialisasikan ke JSON. Titik akhir OpenAPI dibatasi untuk lingkungan pengembangan untuk meminimalkan risiko mengekspos informasi sensitif dan mengurangi kerentanan dalam produksi.

Microsoft.AspNetCore.OpenApi Paket NuGet

Paket ini Microsoft.AspNetCore.OpenApi menyediakan fitur-fitur berikut:

• Dukungan untuk menghasilkan dokumen OpenAPI pada waktu proses dan mengaksesnya melalui titik akhir pada aplikasi.
• Dukungan untuk API "transformer" yang memungkinkan modifikasi dokumen yang dihasilkan.

Untuk menggunakan Microsoft.AspNetCore.OpenApi paket, tambahkan sebagai PackageReference ke file proyek:

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

Untuk mempelajari selengkapnya tentang Microsoft.AspNetCore.OpenApi paket, lihat Membuat dokumen OpenAPI.

Microsoft.Extensions.ApiDescription.Server Paket NuGet

Paket ini Microsoft.Extensions.ApiDescription.Server menyediakan dukungan untuk menghasilkan dokumen OpenAPI pada waktu build dan menserialisasikannya.

Untuk menggunakan Microsoft.Extensions.ApiDescription.Server, tambahkan sebagai PackageReference ke file proyek. Pembuatan dokumen pada waktu build diaktifkan dengan mengatur OpenApiGenerateDocuments properti . Secara default, dokumen OpenAPI yang dihasilkan disimpan ke obj direktori, tetapi Anda dapat menyesuaikan direktori output dengan mengatur OpenApiDocumentsDirectory properti .

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

ASP.NET kode sumber Core OpenAPI di GitHub

• TambahkanOpenApi
• OpenApiDocumentService
• OpenApiOptions

Sumber Tambahan

• Autentikasi dan otorisasi dalam API minimal

Spesifikasi OpenAPI adalah standar bahasa-agnostik pemrograman untuk mendokumen API HTTP. Standar ini didukung dalam API minimal melalui kombinasi API bawaan dan pustaka sumber terbuka. Ada tiga aspek utama untuk integrasi OpenAPI dalam aplikasi:

• Menghasilkan informasi tentang titik akhir di aplikasi.
• Mengumpulkan informasi ke dalam format yang cocok dengan skema OpenAPI.
• Mengekspos skema OpenAPI yang dihasilkan melalui UI visual atau file berseri.

API minimal menyediakan dukungan bawaan untuk menghasilkan informasi tentang titik akhir dalam aplikasi melalui Microsoft.AspNetCore.OpenApi paket. Mengekspos definisi OpenAPI yang dihasilkan melalui UI visual memerlukan paket pihak ketiga.

Untuk informasi tentang dukungan untuk OpenAPI di API berbasis pengontrol, lihat versi .NET 9 dari artikel ini.