ASP .NET Core 8集成Swagger全攻略

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、运行效果