如何用已有OpenAPI替换项目中生成的swagger.json

先明确核心问题 #

你的项目是ASP.NET Core类型，默认的swagger.json是程序运行时动态生成的，不会在项目目录里出现物理文件。要换成你自己的OpenAPI文档，需要修改项目里的Swagger配置代码。

具体操作步骤 #

1. 放置自定义OpenAPI文件到项目 #

• 把你的OpenAPI文档（json或yaml格式均可）放到项目中，推荐放在wwwroot目录，或者新建Docs文件夹专门存储文档。
• 右键点击该文件选择「属性」，将「复制到输出目录」设置为「如果较新则复制」，确保程序运行时能读取到文件。

2. 修改Swagger配置代码 #

打开项目里的Program.cs（若为.NET 5及更早版本则是Startup.cs），找到注册Swagger的代码块，替换原有动态生成逻辑：

.NET 6+ 示例代码

var builder = WebApplication.CreateBuilder(args);

// 注册Swagger服务并加载自定义文档
builder.Services.AddSwaggerGen(c =>
{
    // 自定义文档的路径，根据实际存放位置调整
    var openApiFilePath = Path.Combine(AppContext.BaseDirectory, "custom-openapi.json");
    // 读取自定义OpenAPI文件
    var openApiDoc = new OpenApiStreamReader().Read(File.OpenRead(openApiFilePath), out _);
    // 注册该自定义文档
    c.SwaggerDoc("v1", openApiDoc.Info);
});

var app = builder.Build();

// 配置Swagger UI指向自定义文档
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    // 路径需与文件实际访问路径一致
    c.SwaggerEndpoint("/custom-openapi.json", "自定义API文档 V1");
});

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

3. 处理非wwwroot目录的文件（可选） #

如果OpenAPI文件放在wwwroot以外的目录（比如Docs），需要添加静态文件配置，让程序能访问到：

// 在UseSwagger之前添加这段代码
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(AppContext.BaseDirectory, "Docs")),
    RequestPath = "/Docs"
});

此时SwaggerEndpoint的路径要改为"/Docs/custom-openapi.json"。

4. 验证效果 #

启动项目并打开Swagger UI页面，就能看到自定义的OpenAPI文档内容，原有动态生成的内容会被替换。

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