最小 API とは

完了

API のビルドは、ルーティング、データ ストレージの読み取りおよび書き込み、認証などの多くの機能をサポートする必要があるため、複雑になる可能性があります。 時間を節約するには、必要な機能の多くを提供する、.NET に組み込まれているフレームワークとテンプレートから始めます。 ただし、これらのフレームワークでは、基本的な API を稼働させるまでに、かなりのセットアップが必要になる場合があります。 .NET 6 の minimal API を使えば、そのようなことはありません。 ほんの数行で開始できます。

minimal API を開始するための主な要件は、少なくとも .NET 6 を使用することです。 次に、テキスト エディター (Visual Studio、Visual Studio Code、その他の任意のテキスト エディター) が必要です。 最後に、Windows、macOS、または Linux オペレーティング システムのいずれかを使用できます。

最小 API とは

.NET Web API を開発したことがある場合は、コントローラーを使用するアプローチを使用しています。 さまざまな HTTP 動詞を表すコントローラー クラス メソッドに、特定のタスクを完了するための操作を実行させるという考え方です。 たとえば、GetProducts() は、HTTP 動詞として GET を使用して積を返します。

このコントローラーベースのアプローチと最小 API の違いは何でしょうか?

  • 合理化された Program.cs: コントローラーベースの Web API のテンプレートは、AddControllers メソッドを使用してコントローラーに接続します。 さらに、Swagger に接続して OpenAPI のサポートを提供します。 最小 API では、この接続は既定では行われませんが、必要に応じて Swagger を追加できます。

  • ルーティングが少し異なって見える: ルーティングは、コントローラーベースの Web API とは少し異なっているように見えます。 Web API では、ルーティングについて次のようにコードを記述します。

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        // add my own routes
    });
    

    minimal API では、次のように app インスタンスにルートをすぐに追加します。

    app.MapGet("/todos", await (TodoDb db) => db.Todos.ToListAsync());
    app.MapPost("/todos", await (Todo todo) => {});
    app.MapPut("/todos", (Todo todo) => {});
    app.MapDelete("/todos/{id}", (int id) => {});
    

機能は以前と同じです。 データベースの構成、CORS の設定、認証の追加は、以前と同じように行います。

では、どのように始めればよいのでしょうか。

最小 API で API を作成する

このモジュールで学習する内容について説明します。 ここでは、そのしくみを説明するだけです。 ご自身ではまだ何もしないでください。

dotnet new コマンドを使用すると、新しいプロジェクトが作成されます。

dotnet new web -o PizzaStore -f net8.0

新しく作成された PizzaStore フォルダーには、API プロジェクトが含まれています。

生成されたファイル

生成されたファイルは、コントローラーベースの API で取得するものとほぼ同じです。

bin/
obj/
appsettings.Development.json
appsettings.json
PizzaStore.csproj
Program.cs

PizzaStore.csproj 内には、次のようなエントリがあります。

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <Nullable>enable</Nullable>
</PropertyGroup>

このコードは、.NET 8 を使用していることを示しています。

コードの理解

Program.cs には、API コードが含まれています。 この例は、そのコードがどのように表示されるかを示しています。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();

以前のバージョンの .NET を使用していた場合は、using ステートメントがないことに気付きます。 .NET 6 では、コンパイラによって using ステートメントが判別されます。 ユーザーが気にする必要はありません。

最初の 2 行のコードで、ビルダーを作成します。 builder からアプリケーション インスタンス app を構築します。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

ビルダーには Services プロパティがあります。 Services プロパティを使用すると、CORS、Entity Framework、または Swagger のような機能を追加できます。 次に例を示します。

builder.Services.AddCors(options => {});

Services プロパティでは、ここで使用する機能を API に指定します。 逆に、app インスタンスは、実際にそれを使用するために使用されます。 したがって、app インスタンスを使用してルーティングを設定できます。

app.MapGet("/", () => "Hello World!");

また、app インスタンスを使用してミドルウェアを追加することもできます。 CORS のような機能を使用する方法の例を次に示します。

app.UseCors("some unique string");

Note

ミドルウェアは通常、要求をインターセプトし、認証の確認や、クライアントが CORS に従ってこの操作の実行を許可されていることの確認などのチェックを実行するコードです。 ミドルウェアの実行が完了すると、実際の要求が実行されます。データが読み取られるかストアに書き込まれ、応答が呼び出し元のクライアントに返されます。

最後に、app.Run() によって API が開始され、クライアントからの要求をリッスンします。

コードを実行するには、dotnet run で任意の .NET プロジェクトと同様にプロジェクトを開始します。 既定では、http://localhost:{PORT} で実行されているプロジェクトがあることを意味します。ここで、PORT は 5000 から 5300 の間の値です。

Swagger を使用してドキュメントを追加する

ドキュメントは、API に必要なものです。 自分自身、同僚、および当該 API を使用する可能性があるサードパーティの開発者のために必要です。 API が変更されたときにドキュメントとの同期を維持することが重要です。 API を標準化された方法で記述し、自己文書化されるようにすることをお勧めします。 "自己文書化" すると、コードが変更されたらドキュメントが変更されることを意味します。

Swagger では OpenAPI 仕様が実装されます。 この形式では、ルートだけでなく、受け入れて生成されるデータも記述されます。 Swagger UI は、OpenAPI 仕様を Web サイトとしてレンダリングし、その Web サイトを介して API と対話できるようにするツールのコレクションです。

Swagger と Swagger UI を API で使用するには、次の 2 つの操作を実行します。

  • パッケージをインストールする。 Swagger をインストールするには、次のように Swashbuckle という名前のパッケージをインストールすることを指定します。

    dotnet add package Swashbuckle.AspNetCore --version 6.1.4   
    
  • それを構成する。 パッケージをインストールしたら、コードを使用して構成します。 いくつかの異なるエントリを追加します。

    • 名前空間を追加します。 この名前空間は、後で SwaggerDoc() を呼び出し、API のヘッダー情報を指定するときに必要になります。

      using Microsoft.OpenApi.Models;
      
    • AddSwaggerGen()を追加します。 このメソッドによって、名前やバージョン番号など、API にヘッダー情報が設定されます。

      builder.Services.AddEndpointsApiExplorer();
      builder.Services.AddSwaggerGen(c =>
         {
             c.SwaggerDoc("v1", new OpenApiInfo { Title = "Todo API", Description = "Keep track of your tasks", Version = "v1" });
         });
      
    • UseSwagger()UseSwaggerUI() を追加します。 これらの 2 行のコードは、Swagger を使用すること、また仕様ファイル swagger.json の場所を API プロジェクトに伝えます。

      app.UseSwagger();
      app.UseSwaggerUI(c =>
         {
           c.SwaggerEndpoint("/swagger/v1/swagger.json", "Todo API V1");
         });
      

最小 API のビルドに関係するのはこれですべてです。 プロジェクトを開始し、http://localhost:5000/swagger に移動すると、次のような内容が表示されます。

Screenshot of a Swagger example that shows a to-do A P I.

ハンズオン アクティビティの準備はできましたか? 次のユニットでは、独自の最小 API をビルドします。