ASP.NET Core 中构建时生成 OpenAPI 文档的版本控制问题解析

在 ASP.NET Core 项目中，开发人员经常需要同时支持运行时和构建时两种方式生成 OpenAPI 文档。然而，这两种方式在版本控制配置上存在一些差异，这可能导致文档生成结果不一致的问题。

问题现象

当开发者在 ASP.NET Core 项目中配置 OpenAPI 文档版本时，通常会使用如下代码：

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

这段代码确实能够在运行时正确生成 OpenAPI 2.0 版本的文档，通过访问 /openapi/v1.json 端点可以验证这一点。然而，当使用构建时生成 OpenAPI 文档时，生成的文档却会默认使用 3.0.1 版本，这与运行时配置不符。

技术背景

ASP.NET Core 提供了两种生成 OpenAPI 文档的方式：

1. 运行时生成：通过应用程序运行时动态生成文档
2. 构建时生成：在项目构建过程中静态生成文档

这两种方式使用不同的配置系统，因此需要分别进行配置。

解决方案

要解决构建时生成文档的版本控制问题，需要在项目文件中添加特定的 MSBuild 属性：

<PropertyGroup>
   <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi2_0</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

这个配置会确保构建时生成的 OpenAPI 文档也使用 2.0 版本，与运行时配置保持一致。

最佳实践

为了确保 OpenAPI 文档生成的一致性，建议开发者：

1. 同时配置运行时和构建时的 OpenAPI 版本
2. 在项目文档中明确记录所使用的 OpenAPI 版本
3. 在 CI/CD 流程中加入版本验证步骤，确保两种方式生成的文档版本一致

总结

ASP.NET Core 为 OpenAPI 文档生成提供了灵活的选项，但需要注意运行时和构建时配置的区别。通过正确配置 MSBuild 属性，可以确保两种方式生成的文档版本一致，从而避免潜在的兼容性问题。