C#如何写出健壮的API？ASP.NET Core API版本控制与文档生成（Swagger）

API健壮性设计的关键点

写出健壮的C# API，核心在于稳定性、可维护性和易用性。ASP.NET Core提供了良好的基础支持，但需要合理设计才能应对真实场景。重点包括：输入验证、异常处理、日志记录、响应格式统一和版本控制。

使用 ModelState 验证请求数据，结合 Data Annotations 或 FluentValidation 提升准确性。全局异常过滤器（Exception Filter）捕获未处理异常，避免暴露敏感信息。通过中间件记录请求日志，便于排查问题。

返回结构统一的响应体，例如封装为

ApiResponse<t></t>

API版本控制策略

随着业务演进，API需要迭代更新。直接修改旧接口会影响已有客户端，因此引入版本控制至关重要。

ASP.NET Core 支持多种方式：

/api/v1/users

/api/v2/users

/api/users?version=1.0

推荐使用 URL 路径方式，并配合 Microsoft.AspNetCore.Mvc.Versioning 包实现：

<font face="Consolas">
services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});
</font>

在控制器上标注版本：

<font face="Consolas">
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UserController : ControllerBase
{
    // v1 实现
}
<p>[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class UserController : ControllerBase
{
// v2 实现
}
</font>

Swagger文档生成与多版本支持

Swagger（现称 OpenAPI）是API文档的事实标准。在 ASP.NET Core 中集成 Swashbuckle.AspNetCore 可自动生成交互式文档。

安装包：

<font face="Consolas">
dotnet add package Swashbuckle.AspNetCore
</font>

配置服务：

<font face="Consolas">
services.AddEndpointsApiExplorer();
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });
});
</font>

启用中间件：

<font face="Consolas">
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
});
</font>

结合 API 版本控制后，Swagger 会自动识别不同版本的控制器并分组展示。可通过 Tag 或命名空间进一步组织接口显示顺序。

添加 XML 注释增强文档可读性：

<font face="Consolas">
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApp.xml"));
</font>

在项目文件中启用生成：

<font face="Consolas">
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>1591</NoWarn>
</PropertyGroup>
</font>

总结与最佳实践

构建健壮的 API 不仅是功能实现，更是长期维护的起点。合理使用版本控制避免破坏性变更，Swagger 提供清晰文档降低沟通成本。

建议：

基本上就这些，关键是在开发初期就把版本和文档当成必须项，而不是事后补救。