隨著微服務架構和 RESTful API 的廣泛應用，API 文檔的管理和自動化生成成為了開發中的重要部分。Swagger（現為 OpenAPI）是一款功能強大的工具，它可以自動生成 API 文檔，并提供交互式 UI，幫助開發者、測試人員、前端開發人員等更高效地使用和測試 API。在 .NET Core 中，Swagger 的集成和配置非常簡便，通過 Swashbuckle.AspNetCore 包，我們能夠輕松地實現 API 文檔的自動生成與展示。

本文將圍繞 .NET Core 中 Swagger 的常用配置 進行詳細講解，涵蓋從基礎配置到一些常見的高級定制，包括多版本支持、認證配置、隱藏 API、API 路徑過濾等常見場景。希望通過本文，您能快速掌握如何在 .NET Core 中靈活地配置 Swagger。

---

1. 啟用 Swagger 的基本功能

首先，創建一個新的 .NET Core 項目并安裝 Swashbuckle.AspNetCore 包：

dotnet add package Swashbuckle.AspNetCore

安裝完成后，我們需要在項目中配置 Swagger。通常的基礎配置包含：

• 注冊 Swagger 服務

• 啟用 Swagger UI

配置代碼：

var builder = WebApplication.CreateBuilder(args);// 注冊 Swagger 服務
builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo{Title = "智慧OA系統 API",Version = "v1",Description = "這是智慧OA系統的 API 文檔",});// 啟用 XML 注釋，Swagger 會展示注釋內容var xmlFile = Path.Combine(AppContext.BaseDirectory, "智慧OA系統.xml");c.IncludeXmlComments(xmlFile);
});var app = builder.Build();// 啟用 Swagger 和 Swagger UI
if (app.Environment.IsDevelopment())
{app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系統 API v1");c.RoutePrefix = string.Empty;  // 設置 Swagger UI 路徑});
}app.MapControllers();
app.Run();

解析：

• 在 builder.Services.AddSwaggerGen 中，我們定義了 API 的元數據，如標題、版本、描述等。

• 通過 app.UseSwagger() 啟用 Swagger，app.UseSwaggerUI() 啟用交互式 Swagger UI，方便開發者直接在瀏覽器中查看和測試 API。

---

2. 啟用多版本 API 文檔

在實際開發中，API 會隨著時間的推移不斷進行版本更新。為了方便管理，我們需要為不同版本的 API 提供獨立的 Swagger 文檔。例如，假設我們有 v1 和 v2 兩個版本的 API。

配置代碼：

builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "智慧OA系統 v1", Version = "v1" });c.SwaggerDoc("v2", new OpenApiInfo { Title = "智慧OA系統 v2", Version = "v2" });
});app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系統 v1");c.SwaggerEndpoint("/swagger/v2/swagger.json", "智慧OA系統 v2");
});

解析：

• 通過 AddSwaggerGen 配置多個版本的 API 文檔。

• 使用 UseSwaggerUI 為每個版本提供獨立的 Swagger 端點，允許前端開發人員選擇需要使用的 API 版本。

---

3. API 安全性設置（JWT 認證）

在許多現代應用中，JWT（JSON Web Token）認證已成為一種常見的身份驗證方式。通過 Swagger，我們可以讓開發者方便地在 Swagger UI 中輸入 JWT Token，從而測試需要認證的 API。

配置代碼：

builder.Services.AddSwaggerGen(c =>
{c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme{In = ParameterLocation.Header,Name = "Authorization",Type = SecuritySchemeType.ApiKey,Scheme = "Bearer",BearerFormat = "JWT",Description = "請輸入JWT Token進行認證"});c.AddSecurityRequirement(new OpenApiSecurityRequirement{{new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "Bearer"}},new string[] {}}});
});

解析：

• AddSecurityDefinition 配置了 Swagger 如何接受 API 的認證信息，這里使用了 Bearer 方案，即在請求頭中傳遞 JWT Token。

• AddSecurityRequirement 設置了所有 API 請求都需要提供認證信息。

在 Swagger UI 中，用戶可以通過輸入 JWT Token 來進行身份認證和測試。

---

4. Basic 認證配置

除了 JWT 認證，Basic 認證也是一種常見的認證方式。在某些項目中，你可能需要使用 Basic 認證來保護 API。

配置代碼：

builder.Services.AddSwaggerGen(c =>
{c.AddSecurityDefinition("Basic", new OpenApiSecurityScheme{In = ParameterLocation.Header,Name = "Authorization",Type = SecuritySchemeType.Http,Scheme = "basic",Description = "Basic Authentication"});c.AddSecurityRequirement(new OpenApiSecurityRequirement{{new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "Basic"}},new string[] {}}});
});

解析：

• 通過配置 Basic 認證，我們可以在 Swagger UI 中提供用戶名和密碼來進行 Basic 認證。

• 這種方式適用于不使用 JWT 的傳統認證場景。

---

5. 隱藏某些 API 或控制器

在開發中，通常有一些 API 是僅供內部使用的，或者是某些需要隱藏的 API。這時我們可以通過 ApiExplorerSettings 特性將這些 API 從 Swagger 文檔中排除。

配置代碼：

[ApiExplorerSettings(IgnoreApi = true)]
[Route("api/[controller]")]
public class InternalController : ControllerBase
{[HttpGet]public IActionResult GetInternalData(){return Ok("這是一個內部接口，Swagger 不會顯示");}
}

解析：

• 使用 ApiExplorerSettings(IgnoreApi = true) 特性標記某個控制器或方法，告訴 Swagger 忽略該 API。

• 這對于那些僅供內部使用、且不想暴露的接口非常有用。

---

6. API 請求和響應模型文檔

Swagger 自動根據控制器方法的參數和返回類型生成文檔。在一些復雜的 API 中，你可能需要為請求和響應定義詳細的模型，這樣 Swagger 會根據模型的屬性生成文檔，幫助前端開發人員更好地理解如何調用 API。

配置代碼：

public class RegisterRequest
{public string Username { get; set; }public string Password { get; set; }
}public class RegisterResponse
{public bool Success { get; set; }public string Message { get; set; }
}[HttpPost]
[Route("api/register")]
public IActionResult Register([FromBody] RegisterRequest request)
{var response = new RegisterResponse{Success = true,Message = "注冊成功"};return Ok(response);
}

解析：

• 使用 RegisterRequest 和 RegisterResponse 模型，Swagger 會自動生成相應的文檔，描述請求體和響應體的結構。

---

7. 在生產環境中禁用 Swagger

為了安全起見，我們通常希望在生產環境中禁用 Swagger，防止暴露 API 文檔。你可以通過環境檢查來控制 Swagger 的啟用與禁用。

配置代碼：

if (app.Environment.IsDevelopment())
{app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系統 API v1");});
}

解析：

• 通過 app.Environment.IsDevelopment() 來確保僅在開發環境中啟用 Swagger。

---

8. 自定義 Swagger UI 外觀

Swagger UI 提供了豐富的自定義選項，開發者可以根據自己的需求修改界面的標題、顯示請求時長等信息。

配置代碼：

app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系統 API v1");c.RoutePrefix = string.Empty;c.DocumentTitle = "智慧OA系統 API 文檔";c.DisplayRequestDuration(); // 顯示請求的響應時間
});

解析：

• 通過 DocumentTitle 和 DisplayRequestDuration 等選項自定義 Swagger UI 的外觀和行為。

---

9. 總結

在 .NET Core 中集成 Swagger

可以顯著提高 API 文檔的生成效率和使用體驗。通過本文所述的基本配置和常見的高級配置，您可以根據項目需求對 Swagger 進行定制，從而更好地管理 API 文檔和接口測試。

無論是多版本支持、認證配置、隱藏 API 還是自定義 Swagger UI，靈活使用這些功能可以幫助團隊提高開發效率，減少溝通成本，并確保 API 的正確使用。

希望這篇文章能夠幫助您在項目中更好地整合和配置 Swagger，提高開發體驗與文檔質量。