Asp.NET Core构建时生成的OpenAPI规范文件缺失路由前缀

问题根源 #

你通过项目文件配置的OpenApiGenerateDocumentsOnBuild属于静态代码分析式的文档生成，这个过程不会执行Program.cs中的中间件路由配置（比如MapGroup），因此无法识别你设置的路由前缀。而运行时通过PreSerializeFilter修复Swagger显示的方法，只作用于应用启动后的动态文档生成，对构建阶段的静态生成无效。

推荐解决方案：使用Swashbuckle CLI构建后生成文档 #

这个方案会在构建完成后启动应用宿主，完整加载所有路由配置（包括MapGroup的前缀），生成准确的OpenApi文档，无需硬编码前缀。

1. 安装Swashbuckle.AspNetCore.Cli包
   在项目文件中添加包引用：

   <ItemGroup>
     <PackageReference Include="Swashbuckle.AspNetCore.Cli" Version="6.4.0">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
   

2. 修改项目文件配置
   关闭内置的静态生成，添加构建后执行的CLI命令：

   <PropertyGroup>
     <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)/ApiSpecs</OpenApiDocumentsDirectory>
     <!-- 关闭内置静态生成 -->
     <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild>
   </PropertyGroup>
   
   <Target Name="GenerateOpenApiDocs" AfterTargets="Build">
     <!-- 生成JSON格式的OpenApi文档，v1是你的文档版本 -->
     <Exec Command="dotnet swagger tofile --output $(OpenApiDocumentsDirectory)/swagger.json $(OutputPath)/$(AssemblyName).dll v1" />
     <!-- 如果需要YAML格式，添加下面的命令 -->
     <!-- <Exec Command="dotnet swagger tofile --output $(OpenApiDocumentsDirectory)/swagger.yaml $(OutputPath)/$(AssemblyName).dll v1" /> -->
   </Target>
   

备选方案：硬编码前缀的文档过滤器（不推荐） #

如果必须使用内置静态生成，可以通过自定义文档过滤器手动添加前缀，但需要同步维护Program.cs和过滤器中的前缀，灵活性差：

1. 创建自定义文档过滤器
   在项目中添加以下类：

   using Microsoft.AspNetCore.OpenApi;
   using Microsoft.OpenApi.Models;
   
   public class CustomOpenApiConfig : IConfigureOpenApiDocumentGeneratorOptions
   {
       public void Configure(OpenApiDocumentGeneratorOptions options)
       {
           options.DocumentFilters.Add(new RoutePrefixFilter("/my/prefix"));
       }
   }
   
   public class RoutePrefixFilter : IDocumentFilter
   {
       private readonly string _prefix;
   
       public RoutePrefixFilter(string prefix)
       {
           _prefix = prefix.TrimEnd('/');
       }
   
       public void Apply(OpenApiDocument doc, DocumentFilterContext context)
       {
           var updatedPaths = new OpenApiPaths();
           foreach (var path in doc.Paths)
           {
               updatedPaths.Add($"{_prefix}{path.Key}", path.Value);
           }
           doc.Paths = updatedPaths;
       }
   }
   

2. 配置项目文件加载过滤器
   在项目文件中添加：

   <PropertyGroup>
     <OpenApiDocumentGeneratorSettings>$(MSBuildProjectDirectory)/CustomOpenApiConfig.cs</OpenApiDocumentGeneratorSettings>
   </PropertyGroup>
   

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