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>

API v. API 操作 バージョン API エンドポイント

以降のセクションでは、ASP.NET Core と OpenAPI のドキュメントのコンテキストでの API、API エンドポイント、API 操作の違いについて説明します。

API (アプリケーション プログラミング インターフェイス)

API は、ソフトウェア アプリケーションを構築して操作するための一連の規則とプロトコルです。 さまざまなソフトウェア コンポーネントの通信方法を定義します。 一般的な Web 開発では、"API" は通常、HTTP 経由で機能を公開する Web サービスを指します。

ASP.NET Core では、通常、API は、着信 HTTP 要求を処理して応答を返すコントローラーまたは最小限の API を使用して構築されます。

ASP.NET Core の内部名前付け規則では、"API" を使用する方法が異なる場合があります。 たとえば、 API エクスプローラーでは、"ApiDescription" は実際には完全な API サービスではなく API 操作 を表します。 この区別は内部の名前付け規則を反映しており、ここで使用されるより広範な定義とは異なる場合があります。

API Explorer の詳細については、「 ASP.NET Core の ApiExplorer の概要 」を参照してください。

API 操作

API 操作は、API が提供する特定のアクションまたは機能を表します。 ASP.NET Core では、これは次に対応します。

• MVC スタイル API のコントローラー アクション メソッド
• 最小 API でのルート ハンドラー

各操作は、その HTTP メソッド (GET、 POST、 PUTなど)、パス、パラメーター、応答によって定義されます。

API エンドポイント

API エンドポイントは特定の URL です。

• これは、API によって公開される特定のリソースまたは機能を表します。
• 特定の API 操作と対話するためにクライアントが HTTP 要求を送信する必要がある正確なアドレスを提供します。

エンドポイントは、API のベース URL と、目的のリソースへの特定のパスと、サポートされている HTTP メソッドの組み合わせです。

• コントローラー ベースの API の場合、エンドポイントはルート テンプレートとコントローラーとアクションを組み合わせます。
• 最小 API の場合、エンドポイントは app.MapGet()、 app.MapPost()などを使用して明示的に定義されます。

たとえば、次の操作をサポートする api/products/{id} エンドポイントです。

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

多くの場合、エンドポイントにはクエリ パラメーターが含まれます。たとえば、 GET /api/products?category=electronics&sort=price

OpenAPI のドキュメント

OpenAPI のコンテキストでは、すべてのエンドポイントと操作を含む API 全体について説明しています。 OpenAPI には、API を文書化するための構造化された方法が用意されており、開発者はそれらを操作する方法を理解しやすくなります。

API 操作は、OpenAPI ドキュメントの主な焦点です。 OpenAPI 仕様では、パス (エンドポイント) ごとにグループ化された操作ごとにドキュメントが整理されます。 各操作は、パラメーター、要求本文、応答などの詳細と共に記述されます。 この構造化形式により、ツールはクライアント ライブラリ、サーバー スタブ、および対話型ドキュメントを自動的に生成できます。

OpenAPI ドキュメントの場合:

• ドキュメント全体で API 全体について説明します
• 各パス項目 ( /api/products/{id} など) はエンドポイントを表します
• 各パスの下で、HTTP メソッド (GET、 POST、 PUTなど) によって操作が定義されます。
• 各操作には、パラメーター、要求本文、応答などに関する詳細が含まれています。

OpenAPI JSON 形式の例:

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 操作、および API エンドポイントの比較

次の表は、API、API 操作、および API エンドポイントの違いをまとめたものです。

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

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

その他のリソース

• Minimal API での認証と認可

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

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

Minimal API は、Microsoft.AspNetCore.OpenApi パッケージを使ってアプリ内のエンドポイントに関する情報を生成するための組み込みサポートを提供します。 生成された OpenAPI 定義をビジュアル UI で表示するには、サードパーティ製のパッケージが必要です。

コントローラー ベースの API での OpenAPI のサポートについては、この記事の「.NET 9 バージョン」をご覧ください。