生成 OpenAPI 文档

Microsoft.AspNetCore.OpenApi 包为 ASP.NET Core 中的 OpenAPI 文档生成提供内置支持。 该包提供以下功能：

• 支持在运行时生成 OpenAPI 文档，并通过应用程序上的终结点访问它们。
• 支持“转换器”API，允许修改生成的文档。
• 支持从单个应用生成多个 OpenAPI 文档。
• 利用 System.Text.Json 提供的 JSON 架构支持。
• 与本机 AoT 兼容。

包安装

安装 Microsoft.AspNetCore.OpenApi 包：

Visual Studio

从程序包管理器控制台运行以下命令：

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

运行下面的命令：

dotnet add package Microsoft.AspNetCore.OpenApi

配置 OpenAPI 文档生成

下面的代码：

• 添加 OpenAPI 服务。
• 启用终结点以查看 JSON 格式的 OpenAPI 文档。

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

启动应用并导航到 https://localhost:<port>/openapi/v1.json 以查看生成的 OpenAPI 文档。

用于自定义 OpenAPI 文档生成的选项

以下部分演示如何自定义 OpenAPI 文档生成。

自定义 OpenAPI 文档名称

应用中的每个 OpenAPI 文档都具有唯一的名称。 注册的默认文档名称为 v1。

builder.Services.AddOpenApi(); // Document name is v1

可通过将名称作为参数传递到 AddOpenApi 调用来修改文档名称。

builder.Services.AddOpenApi("internal"); // Document name is internal

文档名称在 OpenAPI 实现中的多个位置显示。

提取生成的 OpenAPI 文档时，文档名称作为请求中的 documentName 参数提供。 以下请求将解析 v1 和 internal 文档。

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

自定义所生成文档的 OpenAPI 版本

默认情况下，OpenAPI 文档生成将创建一个符合 3.0 版 OpenAPI 规范的文档。 以下代码演示了如何修改 OpenAPI 文档的默认版本：

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

自定义 OpenAPI 终结点路由

默认情况下，通过对 MapOpenApi 的调用注册的 OpenAPI 终结点将在 /openapi/{documentName}.json 终结点公开文档。 以下代码演示了如何自定义 OpenAPI 文档注册到的路由：

app.MapOpenApi("/openapi/{documentName}/openapi.json");

可以从终结点路由中删除 documentName 路由参数，但不建议这样做。 从终结点路由中移除 documentName 路由参数时，框架会尝试从查询参数解析文档名称。 在路由或查询中不提供 documentName 可能会导致意外行为。

自定义 OpenAPI 终结点

由于 OpenAPI 文档是通过路由处理程序终结点提供的，因此适用于标准最小终结点的任何自定义项也同样适用于 OpenAPI 终结点。

只有已获授权的用户才能访问 OpenAPI 文档

默认情况下，OpenAPI 终结点不会启用任何授权检查。 但是，授权检查可应用于 OpenAPI 文档。 在以下代码中，只有具有 tester 角色的用户可以访问 OpenAPI 文档：

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

缓存生成的 OpenAPI 文档

每次向 OpenAPI 终结点发送请求时，都会重新生成 OpenAPI 文档。 重新生成使转换器能够将动态应用程序状态合并到其操作中。 例如，使用 HTTP 上下文的详细信息重新生成请求。 在适用的情况下，可以缓存 OpenAPI 文档，以避免针对每个 HTTP 请求执行文档生成管道。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

app.MapOpenApi()
    .CacheOutput();

app.MapGet("/", () => "Hello world!");

app.Run();

在生成时生成 OpenAPI 文档

在典型的 Web 应用程序中，OpenAPI 文档在运行时生成，并通过对应用程序服务器的 HTTP 请求提供服务。

在某些情况下，在应用程序的生成步骤中生成 OpenAPI 文档会很有帮助。 这些方案包括：

• 生成提交到源代码管理的 OpenAPI 文档。
• 生成用于基于规范的集成测试的 OpenAPI 文档。
• 生成从 Web 服务器静态提供的 OpenAPI 文档。

若要在生成时添加对生成 OpenAPI 文档的支持，请安装 Microsoft.Extensions.ApiDescription.Server 包：

Visual Studio

从程序包管理器控制台运行以下命令：

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

在包含项目文件的目录中运行以下命令：

dotnet add package Microsoft.Extensions.ApiDescription.Server

安装后，此包将在生成过程中自动生成与应用程序关联的 Open API 文档，并将其填充到应用程序的输出目录中。

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

自定义生成生成时文档

修改生成的 Open API 文件的输出目录

默认情况下，生成的 OpenAPI 文档将发送到应用程序的输出目录。 若要修改所发出文件的位置，请设置属性中的 OpenApiDocumentsDirectory 目标路径。

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

相对于项目文件解析的值 OpenApiDocumentsDirectory 。 ./使用上述值将在项目文件所在的同一目录中发出 OpenAPI 文档。

修改输出文件名

默认情况下，生成的 OpenAPI 文档的名称与应用程序的项目文件相同。 若要修改发出的文件的名称，请设置 --file-name 属性中的 OpenApiGenerateDocumentsOptions 参数。

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

选择要生成的 OpenAPI 文档

某些应用程序可能配置为针对 API 的各种版本发出多个 OpenAPI 文档，或区分公共 API 和内部 API。 默认情况下，生成时文档生成器将为应用程序中配置的所有文档发出文件。 若要仅针对单个文档名称发出，请OpenApiGenerateDocumentsOptions设置--document-name属性中的参数。

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

在生成生成时文档期间自定义运行时行为

在内部，通过启动应用程序的入口点和插入服务器实现，生成时 OpenAPI 文档生成函数。 这是生成准确的 OpenAPI 文档的要求，因为无法静态分析 OpenAPI 文档中的所有信息。 由于调用应用程序的入口点，因此将调用应用程序启动中的任何逻辑。 这包括将服务注入 DI 容器或从配置中读取的代码。 在某些情况下，必须限制从生成时调用应用程序入口点时将运行的代码路径。 这些方案包括：

• 不从某些配置字符串读取。
• 未注册与数据库相关的服务。

为了限制生成时间生成管道调用这些代码路径，可以在条目程序集的检查后面进行条件，如下所示：

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}