ASP.NET Core API アプリでの OpenAPI のサポート

ASP.NET Core では、コントローラーベースの Minimal API アプリでの OpenAPI ドキュメントの生成がサポートされています。 OpenAPI 仕様は、HTTP API を文書化するためのプログラミング言語に依存しない標準です。 この標準は、ASP.NET Core アプリでは、組み込みの API とオープンソース ライブラリの組み合わせによりサポートされます。 アプリケーションでの OpenAPI 統合には、次の 3 つの重要な側面があります。

• アプリ内のエンドポイントに関する情報を生成します。
• OpenAPI スキーマに一致する形式で情報を収集します。
• 生成された OpenAPI ドキュメントをビジュアル UI またはシリアル化されたファイルを通して公開します。

ASP.NET Core アプリは、Microsoft.AspNetCore.OpenApi パッケージを使ってアプリ内のエンドポイントに関する情報を生成するための組み込みサポートを提供します。

次のコードは、ASP.NET Core の最小限の Web API テンプレートによって生成され、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);
}

前の強調表示されたコードでは、次のようになっています。

• AddOpenApi は、OpenAPI ドキュメントの生成に必要なサービスをアプリケーションの DI コンテナーに登録します。
• MapOpenApi は、JSON にシリアル化された OpenAPI ドキュメントを表示するためのエンドポイントをアプリケーションに追加します。 OpenAPI エンドポイントは開発環境に制限され、機密情報を公開するリスクを最小限に抑え、運用環境の脆弱性を減らします。

Microsoft.AspNetCore.OpenApi NuGet パッケージ

Microsoft.AspNetCore.OpenApi パッケージでは、次の機能が提供されています。

• 実行時の OpenAPI ドキュメントの生成と、アプリケーション上のエンドポイントを介したアクセスのサポート
• 生成されたドキュメントを変更できる "transformer" API のサポート。

Microsoft.AspNetCore.OpenApi パッケージを使用するには、PackageReference としてプロジェクト ファイルに追加します。

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

Microsoft.AspNetCore.OpenApi パッケージの詳細については、「OpenAPI ドキュメントを生成する」をご覧ください。

Microsoft.Extensions.ApiDescription.Server NuGet パッケージ

Microsoft.Extensions.ApiDescription.Server パッケージは、ビルド時に OpenAPI ドキュメントを生成し、シリアル化するためのサポートを提供します。

Microsoft.Extensions.ApiDescription.Server を使用するには、それを PackageReference としてプロジェクト ファイルに追加します。 OpenApiGenerateDocuments プロパティを設定することで、ビルド時のドキュメント生成が有効になります。 既定では、生成された OpenAPI ドキュメントは obj ディレクトリに保存されますが、OpenApiDocumentsDirectory プロパティを設定することで出力ディレクトリをカスタマイズできます。

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

GitHub 上の ASP.NET Core OpenAPI ソース コード

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

その他のリソース

• Minimal API での認証と認可