FastAPI自动生成的OpenAPI文件无法导入Insomnia的兼容问题

FastAPI 默认生成的 OpenAPI 规范（基于 Swagger/OpenAPI 3.x）和 Insomnia 的校验规则存在细节差异：Insomnia 严格遵循 OpenAPI 3.0/3.1 的官方标准，而 FastAPI 部分场景下会生成简化或不符合严格标准的内容，这是兼容问题的核心成因。针对你遇到的错误，以下是具体修复方法：

具体问题修复 #

1. 缺少非空 servers 数组 #

FastAPI 本地开发时可能不会自动生成 servers 字段，可在初始化 FastAPI 实例时手动补充：

from fastapi import FastAPI

app = FastAPI(
    servers=[
        {"url": "http://localhost:8000", "description": "本地开发服务器"}
    ]
)

2. 操作标签未全局定义 #

Insomnia 要求所有路径操作中使用的标签必须在全局 tags 数组中预先定义，FastAPI 允许直接使用未声明的标签，需补充全局标签配置：

app = FastAPI(
    tags=[
        {"name": "users", "description": "用户管理接口"},
        {"name": "items", "description": "物品管理接口"}
    ]
)

# 路径操作中使用已声明的标签
@app.get("/users/", tags=["users"])
def get_users():
    return []

3. exclusiveMinimum 属性类型应为布尔值 #

FastAPI 默认可能生成符合 OpenAPI 3.1 的 exclusiveMinimum 数值格式，但 Insomnia 若采用 3.0 校验规则，要求该字段为布尔值，且必须搭配 minimum 使用。可在 Pydantic 模型中明确配置：

from pydantic import BaseModel, Field

class Item(BaseModel):
    price: float = Field(
        ...,
        minimum=0.0,
        exclusiveMinimum=True  # 布尔值格式，与 minimum 配合
    )

若需强制 FastAPI 生成 OpenAPI 3.0 规范，初始化时指定版本：

app = FastAPI(openapi_version="3.0.2")

4. 需同时定义 minimum 与 exclusiveMinimum #

这是 OpenAPI 3.0 的强制规则，按照上述 Pydantic Field 的配置方式，同时声明 minimum 和 exclusiveMinimum=True 即可解决。

批量修复脚本（可选） #

若不想修改代码，可通过脚本调整生成的 openapi.json：

import json

with open("openapi.json", "r") as f:
    spec = json.load(f)

# 补全 servers 数组
if "servers" not in spec or not spec["servers"]:
    spec["servers"] = [{"url": "http://localhost:8000"}]

# 补全全局未定义的标签
used_tags = set()
for path in spec["paths"].values():
    for op in path.values():
        if "tags" in op:
            used_tags.update(op["tags"])
if "tags" not in spec:
    spec["tags"] = []
existing_tags = {t["name"] for t in spec["tags"]}
for tag in used_tags:
    if tag not in existing_tags:
        spec["tags"].append({"name": tag, "description": ""})

# 修复 exclusiveMinimum 格式为 3.0 兼容的布尔值
def fix_schema(schema):
    if "exclusiveMinimum" in schema:
        if isinstance(schema["exclusiveMinimum"], (int, float)):
            schema["minimum"] = schema["exclusiveMinimum"]
            schema["exclusiveMinimum"] = True
    # 递归处理嵌套结构
    for key in ["properties", "items"]:
        if key in schema:
            if isinstance(schema[key], dict):
                fix_schema(schema[key])
            elif isinstance(schema[key], list):
                for item in schema[key]:
                    fix_schema(item)

fix_schema(spec["components"]["schemas"])

with open("fixed_openapi.json", "w") as f:
    json.dump(spec, f, indent=2)

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