Swagger (現在稱為 OpenAPI) 是一個用于描述 RESTful API 的規范，ASP.NET Core 內置支持通過 Swashbuckle 庫生成 Swagger 文檔。以下是在 ASP.NET Core 8 中實現 Swagger 的完整步驟。

1、添加Swagger?NuGet 包

dotnet add package Swashbuckle.AspNetCore

2、添加Swagger服務和JWT認證支持

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(option =>
{option.SwaggerDoc("v1", new OpenApiInfo{Version = "v1",Title = "后臺管理平臺 API"});//使用XML注釋foreach (var name in Directory.GetFiles(AppContext.BaseDirectory, "*.*", SearchOption.AllDirectories).Where(f => Path.GetExtension(f).ToLower() == ".xml")){option.IncludeXmlComments(name, includeControllerXmlComments: true);}OpenApiSecurityScheme securityScheme = new OpenApiSecurityScheme{Name = "JWT Authentication",Description = "Enter JWT Bearer token **_only_**",In = ParameterLocation.Header,Type = SecuritySchemeType.Http,Scheme = "bearer",BearerFormat = "JWT",Reference = new OpenApiReference{Id = JwtBearerDefaults.AuthenticationScheme,Type = ReferenceType.SecurityScheme}};option.AddSecurityDefinition(securityScheme.Reference.Id, securityScheme);option.AddSecurityRequirement(new OpenApiSecurityRequirement{{securityScheme, Array.Empty<string>()}});
});

3、啟用Swagger中間件

var app = builder.Build();// 開發環境下啟用 Swagger，通常生產環境不推薦啟用Swagger
if (app.Environment.IsDevelopment())
{app.UseSwagger();app.UseSwaggerUI(options =>{options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");options.DocumentTitle = "后臺管理平臺 API";});
}

4、啟用XML文檔注釋

在項目文件中啟用XML文檔生成

<PropertyGroup><GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

或者在Visual Studio打開項目的屬性窗口，在“生成”選項的“輸出”欄目下，勾選“文檔文件”

5、在API方法上添加XML注釋

/// <summary>
/// 授權認證管理
/// </summary>
public class AuthController : BaseController
{/// <summary>/// 獲取版本號/// </summary>/// <returns></returns>[HttpGet][AllowAnonymous]public ResponseResult<string> GetVersion(){try{return ResponseResult<string>.Success("1.0.0");}catch (Exception ex){_logger.LogError("Get version error: {error}", ex.Message);return ResponseResult<string>.Fail(ex.Message);}}
}

6、運行效果