C# Academy · 课时

OpenAPI、版本控制与部署

生成 Swagger/OpenAPI 文档，为 API 进行版本控制，并将 Minimal API 部署到 Azure App Service 或容器。

OpenAPI、版本控制与部署 是 CoddyKit 上的免费 C# Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

最小 API 中的 OpenAPI

OpenAPI（原名 Swagger）可生成交互式 API 文档。在 .NET 9 中，AddOpenApi() 已内置。对于更早的版本，请使用 Swashbuckle.AspNetCore。

使用 Swashbuckle 添加 Swagger

安装 Swashbuckle，在服务中进行配置，然后添加中间件以提供规范和 Swagger UI。

// dotnet add package Swashbuckle.AspNetCore

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opt =>
    opt.SwaggerDoc("v1", new() { Title = "Products API", Version = "v1" }));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

为端点添加 OpenAPI 注解

使用 Produces、ProducesProblem、WithSummary 和 WithDescription 丰富生成的 OpenAPI 规范。

app.MapGet("/products/{id}", GetProduct)
   .WithName("GetProductById")
   .WithSummary("Get a product by ID")
   .WithDescription("Returns the product matching the given numeric ID.")
   .Produces<ProductDto>(200)
   .Produces<ProblemDetails>(404)
   .WithTags("Products");

使用路由组进行 API 版本控制

一种简单的版本控制策略是使用以版本号为前缀的路由组。基本的版本控制不需要额外的包。

var v1 = app.MapGroup("/api/v1").WithTags("v1");
var v2 = app.MapGroup("/api/v2").WithTags("v2");

v1.MapGet("/products", GetProductsV1);
v2.MapGet("/products", GetProductsV2); // different DTO shape

// Clients use /api/v1/products or /api/v2/products

使用 Asp.Versioning 进行标头或查询版本控制

Asp.Versioning.Http 包通过完整的 OpenAPI 集成，为最小 API 添加基于查询字符串、标头和 URL 片段的版本控制。

// dotnet add package Asp.Versioning.Http

builder.Services.AddApiVersioning(opt =>
{
    opt.DefaultApiVersion = new ApiVersion(1, 0);
    opt.AssumeDefaultVersionWhenUnspecified = true;
    opt.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// /products?api-version=2.0
app.MapGet("/products", GetProducts)
   .HasApiVersion(2, 0);

为每个版本生成独立规范

配置 Swashbuckle，为每个版本生成独立的 OpenAPI 文档，使使用者只能看到与其版本相关的端点。

builder.Services.AddSwaggerGen(opt =>
{
    opt.SwaggerDoc("v1", new() { Title = "API", Version = "v1" });
    opt.SwaggerDoc("v2", new() { Title = "API", Version = "v2" });
});

app.UseSwaggerUI(opt =>
{
    opt.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    opt.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});

发布自包含二进制文件

将您的最小 API 发布为自包含的单个二进制文件——目标计算机无需安装 .NET 运行时。

# Publish for Linux x64 as self-contained
dotnet publish -c Release -r linux-x64 --self-contained true

# Run the output binary
./bin/Release/net9.0/linux-x64/publish/MyApi

# Optionally single-file:
# dotnet publish -c Release -r linux-x64 -p:PublishSingleFile=true

使用 Docker 容器化

使用官方 .NET 基础映像将 API 打包到 Docker 映像中。多阶段 Dockerfile 可以保持最终映像较小。

# Dockerfile (multi-stage)
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApi.dll"]

# Build and run
# docker build -t my-api .
# docker run -p 8080:8080 my-api

部署到 Azure App Service

通过 CLI 直接部署到 Azure App Service。该服务会处理扩缩容、证书和自定义域。

# Publish to folder first
dotnet publish -c Release -o ./publish

# Deploy to Azure App Service
az webapp up \
  --name my-products-api \
  --resource-group myRG \
  --runtime DOTNETCORE:9.0 \
  --sku B1

# View logs
az webapp log tail --name my-products-api --resource-group myRG

运行状况检查

添加运行状况检查端点，使编排器（Kubernetes、Azure）能够验证您的 API 正常运行并已准备好处理流量。

builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>()
    .AddUrlGroup(new Uri("https://api.external.com/ping"), "external");

app.MapHealthChecks("/health");
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = hc => hc.Tags.Contains("ready")
});

真实案例：生产环境检查清单

生产环境中的最小 API 应包含以下设置，以确保正确性、可观测性和安全性。

// builder configuration
builder.Services.AddProblemDetails();
builder.Services.AddHealthChecks();
builder.Services.AddRateLimiter(...);
builder.Services.AddOutputCache();

// app pipeline
app.UseHttpsRedirection();
app.UseExceptionHandler();
app.UseRateLimiter();
app.UseOutputCache();
app.UseAuthentication();
app.UseAuthorization();

app.MapHealthChecks("/health");
// ... your endpoints
app.Run();

快速检查

在最小 API 中，哪个方法会使端点元数据（Produces、WithSummary 等）对 OpenAPI 工具可见？

回顾：OpenAPI、版本控制与部署

要点：

AddEndpointsApiExplorer + Swashbuckle = 适用于最小 API 的 Swagger UI
使用 Produces、WithSummary、WithTags 添加注解，以生成内容丰富的 OpenAPI 文档
通过路由组实现简单版本控制；对于高级场景，使用 Asp.Versioning
发布自包含文件或 Docker 映像，以实现灵活部署
添加运行状况检查，为 Kubernetes/Azure 就绪探针提供支持

常见问题解答

「OpenAPI、版本控制与部署」课时是免费的吗？

是的 — 「OpenAPI、版本控制与部署」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「OpenAPI、版本控制与部署」这节课中我会学到什么？

生成 Swagger/OpenAPI 文档，为 API 进行版本控制，并将 Minimal API 部署到 Azure App Service 或容器。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「OpenAPI、版本控制与部署」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy