一、概述

構建最小 API，以創建具有最小依賴項的 HTTP API。 它們非常適合于需要在 ASP.NET Core 中僅包括最少文件、功能和依賴項的微服務和應用。 本文介紹使用 ASP.NET Core 生成最小 API 的基礎知識，將創建以下 API：

API（應用程序接口）	描述	請求正文	響應正文
GET /todoitems	獲取所有待辦事項	無	待辦事項的數組
GET /todoitems/complete	獲取已完成的待辦事項	無	待辦事項的數組
GET /todoitems/{id}	按 ID 獲取項	無	待辦事項
POST /todoitems	添加新項	待辦事項	待辦事項
PUT /todoitems/{id}	更新現有項	待辦事項	無
DELETE /todoitems/{id}	刪除項	無	無

二、開發環境

Deepin 20.9、.Net Core 8、VS Code

開發環境搭建參考：.NET SDK 各操作系統開發環境搭建

三、創建 TodoApi 項目

創建一個空模板項目，

Program.cs 文件包含以下代碼：

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

前面的代碼：

• 創建具有預配置默認值的 WebApplicationBuilder 和 WebApplication。
• 創建返回 / 的 HTTP GET 終結點 Hello World!

運行項目后，瀏覽器訪問 http://localhost:5026 ，Hello World! 將顯示在瀏覽器中。Program.cs 文件包含了一個最小但完整的應用。

四、添加 NuGet 包

需要添加 ORM 框架 EF CORE，搜索 Microsoft.EntityFrameworkCore.InMemory，然后安裝，

安裝完成，

除此之外，還需要安裝 Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore 用于捕獲異常，注意版本要適配 SDK，不然會報錯rror CS1061: “IServiceCollection”未包含“AddDatabaseDeveloperPageExceptionFilter”的定義，并且找不到可接受第一個“IServiceCollection”類型參數的可訪問擴展方法“AddDatabaseDeveloperPageExceptionFilter”(是否缺少 using 指令或程序集引用?)

五、模型和數據庫上下文類

在項目文件夾中，創建名為 Todo.cs 的文件為此應用創建模型，包含以下代碼：

namespace TodoApi;public class Todo
{public int Id { get; set; }public string? Name { get; set; }public bool IsComplete { get; set; }
}

該模型是一個表示應用管理的數據的類。

接著創建名為 TodoDb.cs 的文件定義數據庫上下文，它是為數據模型協調實體框架功能的主類， 此類從 Microsoft.EntityFrameworkCore.DbContext 類派生，包含以下代碼：

namespace TodoApi;using Microsoft.EntityFrameworkCore;class TodoDb : DbContext
{public TodoDb(DbContextOptions<TodoDb> options): base(options) { }public DbSet<Todo> Todos => Set<Todo>();
}

六、添加 API 代碼

將 Program.cs 文件的內容替換為以下代碼：

using Microsoft.EntityFrameworkCore;using TodoApi;var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
var app = builder.Build();app.MapGet("/todoitems", async (TodoDb db) =>await db.Todos.ToListAsync());app.MapGet("/todoitems/complete", async (TodoDb db) =>await db.Todos.Where(t => t.IsComplete).ToListAsync());app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>await db.Todos.FindAsync(id)is Todo todo? Results.Ok(todo): Results.NotFound());app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{db.Todos.Add(todo);await db.SaveChangesAsync();return Results.Created($"/todoitems/{todo.Id}", todo);
});app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{var todo = await db.Todos.FindAsync(id);if (todo is null) return Results.NotFound();todo.Name = inputTodo.Name;todo.IsComplete = inputTodo.IsComplete;await db.SaveChangesAsync();return Results.NoContent();
});app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{if (await db.Todos.FindAsync(id) is Todo todo){db.Todos.Remove(todo);await db.SaveChangesAsync();return Results.NoContent();}return Results.NotFound();
});app.Run();

其中，以下這個代碼段將數據庫上下文添加到依賴關系注入 (DI) 容器，并且允許顯示與數據庫相關的異常：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
var app = builder.Build();

DI 容器提供對數據庫上下文和其他服務的訪問權限。

七、使用 Swagger 創建 API 測試 UI

.NET 包 NSwag.AspNetCore 集成了 Swagger 工具，可用于生成遵循 OpenAPI 規范的測試 UI：

• NSwag：將 Swagger 直接集成到 ASP.NET Core 應用程序中的 .NET 庫，提供了中間件和配置。
• Swagger：一組開放源代碼工具（如 OpenAPIGenerator 和 SwaggerUI），用于生成遵循 OpenAPI 規范的 API 測試頁。
• OpenAPI 規范：基于控制器和模型中的 XML 和屬性注釋，描述 API 功能的文檔。

安裝 Swagger 工具之后，配置 Swagger 中間件：

using Microsoft.EntityFrameworkCore;
using NSwag.AspNetCore;
using TodoApi;var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(config =>
{config.DocumentName = "TodoAPI";config.Title = "TodoAPI v1";config.Version = "v1";
});
var app = builder.Build();

在前面的代碼中：

• builder.Services.AddEndpointsApiExplorer();：啟用 API 資源管理器，該服務提供有關 HTTP API 的元數據。 該 API 資源管理器由 Swagger 用于生成 Swagger 文檔。

• builder.Services.AddOpenApiDocument(config => {...});：將 Swagger OpenAPI 文檔生成器添加到應用程序服務，并配置它以提供有關 API 的詳細信息，例如其標題和版本。

在 app 行中定義 var app = builder.Build(); 后，添加代碼：

var app = builder.Build();
if (app.Environment.IsDevelopment())
{app.UseOpenApi();app.UseSwaggerUi(config =>{config.DocumentTitle = "TodoAPI";config.Path = "/swagger";config.DocumentPath = "/swagger/{documentName}/swagger.json";config.DocExpansion = "list";});
}

通過前面的代碼，Swagger 中間件可以為生成的 JSON 文檔和 Swagger UI 提供服務。 Swagger 僅在開發環境中啟用。 在生產環境中啟用 Swagger 可能會公開有關 API 結構和實現的潛在敏感詳細信息。

八、測試發布數據

Program.cs 中的以下代碼創建 HTTP POST 終結點 /todoitems 以將數據添加到內存中數據庫：

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{db.Todos.Add(todo);await db.SaveChangesAsync();return Results.Created($"/todoitems/{todo.Id}", todo);
});

運行應用。 瀏覽器顯示 404 錯誤，因為不再存在 / 終結點。訪問 http://localhost:5026/swagger/index.html 可以看到 Swagger 文檔 UI，

選擇 Post /todoitems 接口進行測試，

新增數據后，我們通過調用 Get todoitems 接口查詢結果，

參考文檔

• 教程：使用 ASP.NET Core 創建最小 API