C# Academy · 课时

生成 OpenAPI 文档

Q: 「生成 OpenAPI 文档」这节课中我会学到什么？

生成机器可读的 API 规范。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

生成机器可读的 API 规范。

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

什么是 OpenAPI

OpenAPI 是 HTTP API 的一种标准化、机器可读的描述。您可以据此生成文档、客户端 SDK 和测试工具。

.NET 9 提供内置的 OpenAPI 文档生成功能，对于许多应用来说，这取代了较旧的 Swashbuckle 依赖项。

// OpenAPI document = JSON describing paths, schemas, params

Microsoft.AspNetCore.OpenApi 包

内置支持位于 Microsoft.AspNetCore.OpenApi 中。在 .NET 9 模板中，该包已经被引用。

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

在服务配置中使用 AddOpenApi 注册文档生成器。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi 会在一个端点公开生成的文档。默认情况下，文档位于 /openapi/v1.json。

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

仅限开发环境

通常只在开发环境中公开该文档，以避免在生产环境中泄露 API 的接口范围。

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

描述端点

OpenAPI 元数据会根据您的代码得到补充。请在最小 API 端点上使用 WithSummary、WithDescription 和 WithTags。

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

记录响应

声明响应类型和状态代码，以便文档准确列出它们。

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

文档转换器

使用传入 AddOpenApi 的文档转换器自定义整个文档——标题、版本和服务器。

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

操作转换器

操作转换器可以调整单个操作——例如，为每个端点添加一个通用标头参数。

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

添加用户界面

内置生成器会生成 JSON 文档，但不会提供用户界面。将它与 Scalar 或 Swagger UI 之类的查看器搭配使用。

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

在构建时生成

您可以使用 Microsoft.Extensions.ApiDescription.Server 工具在构建过程中生成 OpenAPI 文件（无需运行服务器），这对 CI 客户端生成很有帮助。

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

快速检查

请确认 .NET 9 的 OpenAPI 基础知识。

回顾

您生成了 OpenAPI 文档：

AddOpenApi() 注册生成器；MapOpenApi() 提供 JSON 文档。
使用 WithSummary、Produces 和标签补充端点信息。
文档转换器和操作转换器可以自定义输出。
与 Scalar 或 Swagger UI 搭配，提供交互式视图。

接下来：记录版本化 API 的文档。

常见问题解答

「生成 OpenAPI 文档」课时是免费的吗？

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

「生成 OpenAPI 文档」这节课中我会学到什么？

生成机器可读的 API 规范。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

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

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

「生成 OpenAPI 文档」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 C# Academy