当前位置：首页 > news >正文

ASP .NET Core 8集成Swagger全攻略

news 2025/7/17 8:19:53

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);}}
}