ASP.NET Core构建时如何自定义OpenAPI规范生成的文件名格式

问题 #

按照以下步骤创建了.NET 8 Web API项目并配置构建时自动生成OpenAPI文档：

dotnet new webapi --framework net8.0
dotnet add package Microsoft.Extensions.ApiDescription.Server

项目配置文件内容如下：

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>

    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.3" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="8.0.3">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

当前多版本API场景下，生成的文档文件为SampleWebApi.json（对应v1版本）和SampleWebApi_v2.json（对应v2版本），希望修改生成逻辑实现以下两种需求之一：

• 所有版本的文档文件名都包含版本号（如SampleWebApi_v1.json和SampleWebApi_v2.json）
• 修改文件名格式为SampleWebApi.v1.json和SampleWebApi.v2.json

解决方案 #

1. 让所有版本文档都带版本号 #

默认未显式指定版本的API会被识别为v1，生成的文档文件名不带版本后缀。要让v1版本也带上版本号，需在Program.cs中显式配置v1版本的Swagger文档：

builder.Services.AddSwaggerGen(c =>
{
    // 显式配置v1版本文档
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "SampleWebApi", Version = "v1" });
    // 保持v2版本的原有配置
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "SampleWebApi", Version = "v2" });
});

完成配置后，构建项目时就会生成SampleWebApi_v1.json和SampleWebApi_v2.json两个文件。

2. 修改文件名格式为点分隔样式 #

默认文件名生成逻辑由Microsoft.Extensions.ApiDescription.Server的MSBuild任务控制，无直接配置属性可修改分隔符，但可通过自定义MSBuild目标覆盖文件名生成规则：
在项目配置文件中添加以下内容：

<Target Name="CustomizeOpenApiDocumentNames" BeforeTargets="GenerateOpenApiDocuments">
  <ItemGroup>
    <OpenApiDocument Update="@(OpenApiDocument)">
      <!-- 自定义文件名格式为"标题.版本号.json" -->
      <FileName>$(OpenApiDocument.Title).%(OpenApiDocument.Version).json</FileName>
    </OpenApiDocument>
  </ItemGroup>
</Target>

该目标会在生成OpenAPI文档前修改每个文档的文件名，最终生成SampleWebApi.v1.json和SampleWebApi.v2.json。

若要同时满足"所有版本都带版本号"和"点分隔格式"，需先按第一种方法在Program.cs中显式配置v1的SwaggerDoc，再添加上述MSBuild目标即可。

内容的提问来源于stack exchange，提问作者Wesley