API文檔對於團隊合作與第三方整合至關重要。ASP.NET Core 提供了內建的Swagger工具，可以自動生成API文檔，方便開發者與用戶查閱。本篇將講解如何使用Swagger在ASP.NET Core專案中生成清晰的API文檔。

1. Swagger與ASP.NET Core的整合

Swagger是一個開源工具，可以自動生成API的文檔和測試接口。透過它，開發者和使用者可以更直觀地了解API的結構，並能快速進行API測試。

要在ASP.NET Core專案中啟用Swagger，我們首先需要安裝Swashbuckle.AspNetCore套件。可以在NuGet Package Manager中安裝，也可以使用以下命令：

dotnet add package Swashbuckle.AspNetCore

安裝完成後，我們需要對專案進行一些基本配置。

2. 配置Swagger

在Startup.cs文件中，我們需要對Swagger進行配置。首先，在ConfigureServices方法中添加Swagger服務：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "My API",
            Version = "v1"
        });
    });
}

然後，在Configure方法中啟用Swagger中介軟體，使其可以生成API文檔頁面：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

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

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

這樣，我們的API將有一個Swagger UI頁面，可以通過/swagger路徑訪問。

3. 測試與查看API文檔

完成以上配置後，啟動應用並在瀏覽器中訪問 http://localhost:5000/swagger（或根據應用的端口號進行調整），你將看到自動生成的API文檔頁面。該頁面列出了所有的API端點及其對應的請求和回應格式。

4. 自訂Swagger文檔

除了基本配置外，Swagger還提供了多種選項來自定義文檔。你可以為API的每個操作添加註釋，讓生成的文檔更具可讀性。在控制器和操作方法上添加XML註釋，並在Startup.cs中啟用XML註釋支持：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

確保在專案的屬性中啟用了生成XML文檔的選項，以便Swagger可以讀取這些註釋。

5. 小結

透過Swagger與ASP.NET Core的整合，我們可以輕鬆生成完整的API文檔，提升開發和使用API的效率。不僅如此，還可以根據需求自訂API文檔，使其更加符合專案要求。這樣的文檔對於開發團隊和API的使用者來說都是至關重要的工具。