ASP.NET Core 中的 OpenAPI XML 文档注释支持

ASP.NET Core XML 文档处理会自动提取代码注释以填充 API 文档，确保代码和文档保持同步。 只要项目配置为生成 XML 文档文件，XML 文档注释中的元数据将包含在生成的 OpenAPI 文档中，而无需更改应用代码。 在应用程序集和启用了 XML 文档的引用程序集内，XML 文档注释会被自动检测到。

ASP.NET Core 处理 XML 文档标记，例如：<c>、、<code>、<list><para>、<paramref>、<typeparamref>、 <see>和<seealso>。 对于使用对其他元素的引用的 XML 文档标记，例如 <see cref="SomeOtherType">，实现会去除 XML 标记，并将引用映射到纯文本以包含在 OpenAPI 文档中。

ASP.NET Core XML 文档处理不会影响运行时性能。 源生成器在编译时处理 XML 文档并缓存结果，在呈现 OpenAPI 文档时，运行时开销最小。 此外，可以使用 输出缓存 在运行时缓存 OpenAPI 文档以进一步优化性能。

本文包含一个 示例应用 ，该 Microsoft.AspNetCore.OpenApi 应用演示包将有关类型的 XML 文档注释集成到 OpenAPI 文档中的能力。 示例应用是生成 OpenAPI 文档的最小 ASP.NET 核心 Web API 项目。 XML 文档注释用于填充生成的 OpenAPI 文档中的摘要、说明、参数信息和响应详细信息。

下图显示了将 XML 文档注释集成到示例应用的 OpenAPI 文档中的 Scalar UI：

支持的 XML 文档标记

• <summary>
• <remarks>
• <param>
• <returns>
• <response>
• <example>
• <deprecated>
• <inheritdoc>

记录 HTTP 响应

使用 <response> 标记和 code 属性记录 HTTP 响应：

/// <summary>
/// Retrieves a specific project board by ID.
/// </summary>
/// <param name="id">The ID of the project board to retrieve.</param>
/// <returns>The requested project board.</returns>
/// <response code="200">Returns the requested project board.</response>
/// <response code="404">If the project board is not found.</response>
public static IResult GetProjectBoardById(int id)
{
    var board = Boards.FirstOrDefault(b => b.Id == id);
    if (board == null)
    {
        return Results.NotFound();
    }
    return Results.Ok(board);
}

添加示例

若要向文档添加示例，请使用 <example> 类型标记或 example 参数的属性：

/// <example>{"name":"Sample","value":42}</example>
/// <param name="id" example="42">The unique identifier</param>

自定义 XML 文档行为

以下部分介绍如何启用和自定义 XML 文档支持。

在 ASP.NET 核心 API 项目中启用 XML 文档

1. 在项目文件中启用 XML 文档：

   <Project Sdk="Microsoft.NET.Sdk">
   
     <PropertyGroup>
       <TargetFramework>net10.0</TargetFramework>
       <ImplicitUsings>enable</ImplicitUsings>
       <Nullable>enable</Nullable>
       <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
   
   </Project>
   

2. 在服务配置中使用 AddOpenApi 方法。 无需配置，源生成器将处理其余配置。

   using Api;
   using Scalar.AspNetCore;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddOpenApi();
   
   var app = builder.Build();
   
   if (app.Environment.IsDevelopment())
   {
       app.MapOpenApi();
       app.MapScalarApiReference();
   }
   
   app.Map("/", () => Results.Redirect("/scalar/v1"));
   app.MapProjectBoardApis();
   app.MapTodoApis();
   
   app.Run();
   

源生成器检测所有标准重载：

• AddOpenApi()
• AddOpenApi("v1")
• AddOpenApi(options => {})
• AddOpenApi("v1", options => {})

每个重载都会被拦截，以自动包含 XML 文档转换器。 当 documentName 参数不是一个字面值字符串表达式时，源生成器不会处理重载。 例如，在以下情况下未注册转换器：

var documentName = "v1";
builder.Services.AddOpenApi(documentName); // No XML support

添加 XML 文档源

Microsoft.AspNetCore.OpenApi NuGet 包会自动解析来自以下位置的 XML 文档注释：

• 设置 GenerateDocumentationFile 属性时的应用程序程序集。 在示例应用中，API 项目。

  <Project Sdk="Microsoft.NET.Sdk">
  
    <PropertyGroup>
      <TargetFramework>net10.0</TargetFramework>
      <ImplicitUsings>enable</ImplicitUsings>
      <Nullable>enable</Nullable>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
    </PropertyGroup>
  
  </Project>
  

• 通过 ProjectReferences 引用的具有 GenerateDocumentationFile 属性集的任何项目。 在示例应用中，Models 项目：

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
    <PropertyGroup>
      <TargetFramework>net10.0</TargetFramework>
      <Nullable>enable</Nullable>
      <ImplicitUsings>enable</ImplicitUsings>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.25161.17" />
      <PackageReference Include="Scalar.AspNetCore" Version="2.0.30" />
    </ItemGroup>
  
    <ItemGroup>
      <ProjectReference Include="..\models\Models.csproj" />
    </ItemGroup>
  
  </Project>
  

实现在编译时静态发现 XML 文件。 项 AdditionalFiles 组指定 XML 文件的其他源：

<ItemGroup>
  <PackageReference Include="Some.Package" Version="10.0.0"
                    GeneratePathProperty="true" />
</ItemGroup>

<ItemGroup>
  <AdditionalFiles Include="$(PkgSome_Package)/lib/net10.0/Some.Package.xml" />
</ItemGroup>

若要包括引用程序集中的 XML 文档文件，请将其作为 AdditionalFiles 添加到项目中：

<ItemGroup>
  <AdditionalFiles Include="Path/To/AssemblyDoc.xml" />
</ItemGroup>

可以将 XML 文档注释处理配置为访问其他程序集中的 XML 注释。 这对于为当前程序集外部定义的类型（如 ProblemDetails 命名空间中的 Microsoft.AspNetCore.Http 类型）生成文档非常有用。 此配置是使用项目生成文件中的指令完成的。 以下示例演示如何配置 XML 注释生成器以访问程序集中 Microsoft.AspNetCore.Http 类型的 XML 注释，其中包括类 ProblemDetails ：

<Target Name="AddOpenApiDependencies" AfterTargets="ResolveReferences">
  <ItemGroup>
    <AdditionalFiles
          Include="@(ReferencePath->'
            %(RootDir)%(Directory)%(Filename).xml')"
          Condition="'%(ReferencePath.Filename)' ==
           'Microsoft.AspNetCore.Http.Abstractions'"
          KeepMetadata="Identity;HintPath" />
  </ItemGroup>
</Target>

禁用 XML 文档支持

若要关闭 XML 文档集成，请从 Analyzers 项组中删除源生成器。 删除源生成器可防止在编译期间使用它。

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.25161.17" />
    <PackageReference Include="Scalar.AspNetCore" Version="2.0.30" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\models\Models.csproj" />
  </ItemGroup>

  <Target Name="DisableCompileTimeOpenApiXmlGenerator" BeforeTargets="CoreCompile">
    <ItemGroup>
      <Analyzer Remove="$(PkgMicrosoft_AspNetCore_OpenApi)/analyzers/dotnet/cs/Microsoft.AspNetCore.OpenApi.SourceGenerators.dll" />
    </ItemGroup>
  </Target>

</Project>

源生成器实现

XML 文档功能作为源生成器实现。 源生成器在编译时分析 XML 文档注释，并注入将这些注释转换为 OpenAPI 元数据的代码。 XmlCommentGenerator 从两个源中提取 XML 注释：

• XML 文档文件以 AdditionalFiles 的形式通过 ParseXmlFile 实现传递。
• 通过 ParseCompilation 实现从目标程序集自己的代码中提取 XML 注释。

这两个源之间的区别非常重要。 传递为 AdditionalFiles 的 XML 文档文件是静态的。 目标程序集中的 XML 注释来自 Roslyn 的 XML 文档注释提供程序。 XML 文档注释提供程序增强了将 XML 注释连接到与其关联的编译符号的功能。 这对 <inheritdoc /> 解析在实现中发生的方式有影响，将在下一节讨论。

XML 注释将分析为结构化 XmlComment 对象，其中包含：

• 摘要、说明、备注、返回、值部分。
• 包含名称、说明和示例的参数文档。
• 包含状态代码和说明的响应文档。
• 支持示例和已弃用的标记。

处理复杂类型

XML 注释处理可为各种类型生成准确且完整的 OpenApi 说明，并支持复杂的方案。 但是，如果在处理复杂类型时遇到错误，则进程会正常绕过该类型。

这样，可能导致生成错误的方案现在只会导致缺少元数据，从而避免生成失败。

即使引用的程序集的文档 ID 包含返回类型后缀，XML 文档注释也能正确合并。 因此，所有有效的 XML 注释都可靠地包含在生成的 OpenAPI 文档中，从而提高了使用引用程序集的 API 的文档准确性和完整性。

<inheritdoc/>

生成器支持 <inheritdoc> 标记，只要 它们存在于编译程序集中，就会继承文档。 <inheritdoc /> 标记表示注释必须从以下位置解析：

• 基类
• 实现的接口
• 重写的基本方法

将 <inheritdoc /> 放置在符号上时，源生成器：

• 在编译中使用符号的知识来发现与符号关联的基类和接口。
• 支持自动解析它们
• 替换继承的文档注释中的泛型类型参数，跨继承边界保留类型引用。

自动解析行为目前可用于编译下的程序集中存在的 XML 文档注释， 而不适用于 引用的项目或包中的 XML 文档标记。 在后一个情景中，XML 文档注释：

• 仅以文本形式呈现。
• 不要为以下内容提供无关紧要的策略：
  • 将文本内容与编译符号相关联。
  • 开发对与类型关联的继承层次结构的理解。

XML 文档注释 ProjectReferences 会自动解析，不需要其他配置。

下载并运行 API 示例

下载本文 的示例代码 。

若要运行示例，请导航到 api 目录并输入 dotnet run。

cd api
dotnet run

显示了类似下面的输出：

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5052
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: ~/git/aspnet-openapi-xml/api

导航到 http://localhost:5052/ 查看用于与应用交互的 Scalar UI。 Scalar UI 包括关于各种元素的汇总和说明，这些信息来源于 XML 文档注释。

其他资源

• 源生成器实现说明
• 可以在 ASP.NET Core 存储库中找到源生成器实现。
• 生成 OpenAPI 文档
• 使用生成的 OpenAPI 文档
• .NET OpenAPI 工具命令参考和安装