使用 Swashbuckle 記錄 API

已完成

Swashbuckle 是 NuGet 套件，可讓您自動為 ASP.NET Web API 專案產生 Swagger 文件。 Swagger 是一項可協助開發人員設計、建置、記錄及取用 RESTful API 的工具。 透過 Swashbuckle，您可以使用描述 API 端點、參數和回應的屬性來標註程式碼，輕鬆地將 Swagger 文件新增至 Web API 專案。 Swashbuckle 接著會使用此資訊來產生 Swagger JSON 檔案，可用來產生互動式 API 文件、用戶端 SDK 等等。

Swashbuckle 有三個主要元件：

• Swashbuckle.AspNetCore.Swagger：Swagger 物件模型和中間件，將 SwaggerDocument 物件公開為 JSON 端點。

• Swashbuckle.AspNetCore.SwaggerGen：一個 Swagger 產生器，會直接從您的路由、控制器和模型建置 SwaggerDocument 物件。 它通常會結合 Swagger 端點中介軟體，以便自動公開 Swagger JSON。

• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的內嵌版本。 它可以解譯 Swagger JSON，建置豐富、可自訂的 Web API 功能描述體驗。 其中包括公用方法的內建測試載入器。

下列 dotnet add 命令會安裝 Swashbuckle NuGet 套件：

dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0

新增和設定 Swagger 中介軟體

將 Swagger 產生器新增至 Program.cs 中的服務集合。

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

注意

只有最少 API 才需要呼叫上一個範例中顯示的 AddEndpointsApiExplorer 呼叫。

此外，在 Program.cs 中啟用中介軟體來提供產生的 JSON 文件和 Swagger UI：

app.UseSwagger();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI();
}

Swagger UI 的預設端點為 http:<hostname>:<port>/swagger。

注意

SwaggerUI 在您的開發環境中非常有用。 它可以在生產環境中啟用，但在這麼做之前您應該先考慮特定應用程式的任何安全性需求。

自訂和擴充 Swagger 文件

Swagger 提供用來記錄物件模型和自訂 UI 的選項。 傳遞至 AddSwaggerGen 方法的設定動作可以透過 OpenApiInfo 類別包含其他資訊。

下列程式碼範例示範如何新增資訊以顯示在 API 文件中。

// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Fruit API",
        Description = "API for managing a list of fruit their stock status.",
        TermsOfService = new Uri("https://example.com/terms")
    });
});

Swagger UI 會顯示版本和新增的資訊：

您可以使用 .WithTags 選項將 API 中的作業組成群組。 您也可以使用 .WithSummary 選項來新增描述作業的描述性文字。 下列範例程式代碼示範如何使用 .WithTags 將POST作業分組為 貼文 群組和 水果 群組。 其也會將 .WithSummary 選項中指定的摘要新增至作業。

app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
    db.Fruits.Add(fruit);
    await db.SaveChangesAsync();

    return Results.Created($"/{fruit.Id}", fruit);
})
    .Produces<Fruit>(201)
    .WithTags("post", "fruits")
    .WithSummary("Create a new fruit");

Swagger UI 會顯示指定的分組和摘要描述。