你遇到的这个问题，是 Swagger / OpenAPI 常见错误之一：

Unable to render this definition: The provided definition does not specify a valid version field.

意思是：你提供的 Swagger / OpenAPI JSON 或 YAML 文件缺少必要的版本字段，Swagger UI 无法渲染。下面我帮你分析原因并给出解决方法。

🧩 一、问题根源

OpenAPI（Swagger）规范要求在顶层必须指定版本字段：

1️⃣ Swagger 2.0

{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {}
}
  • swagger：必须是 "2.0"
  • info.version：必须指定 API 版本
  • paths：至少存在一个空对象 {}

2️⃣ OpenAPI 3.0.x

{
  "openapi": "3.0.3",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {}
}
  • openapi：必须是 "3.0.x"
  • info.version：必须指定
  • paths：必须存在

❌ 如果缺少 swagger 或 openapi 字段，Swagger UI 就会报你看到的这个错误。

🧩 二、解决步骤

  1. 确认你的 Swagger 文件版本
  • JSON/YAML 顶层是否有：
    • "swagger": "2.0" 或 "openapi": "3.0.3"
  • info 对象是否包含：
    • "title"
    • "version"
  1. 检查生成工具
  • 如果你用的是 ASP.NET Core + Swashbuckle：
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1"
    });
});

❌ 常见错误：

  • 没有设置 Version
  • 没有调用 SwaggerDoc
  • 返回空的或不符合 OpenAPI 的 JSON
  1. 检查输出的 JSON/YAML 文件

打开 /swagger/v1/swagger.json（默认路径），确保顶层类似：

{
  "openapi": "3.0.1",
  "info": {
    "title": "My API",
    "version": "v1"
  },
  "paths": {}
}

🧩 三、常见修复方式

1️⃣ ASP.NET Core / Swashbuckle 示例

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "这是一个示例 API"
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

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

✅ 注意：

  • SwaggerDoc 第一个参数 "v1" 是 Swagger 文档名称
  • OpenApiInfo.Version 必须指定（如 "v1" 或 "1.0.0"）

2️⃣ JSON/YAML 文件手动修复

  • JSON：
{
  "openapi": "3.0.3",
  "info": {
    "title": "Example API",
    "version": "1.0.0"
  },
  "paths": {}
}
  • YAML：
openapi: "3.0.3"
info:
  title: Example API
  version: 1.0.0
paths: {}

3️⃣ 其他注意事项

  • 如果你手动生成 Swagger 文件，一定要保证顶层 openapi 或 swagger 字段存在
  • info.version 不能留空
  • Swagger UI 不支持空 JSON，必须至少有空的 paths: {}

总结：

错误原因解决方法
顶层没有 swagger 或 openapi 字段添加 "swagger": "2.0" 或 "openapi": "3.0.3"
info.version 为空或缺失设置 Version，如 "v1" 或 "1.0.0"
JSON/YAML 文件结构不完整至少包含 info 和空的 paths