Connexion v3测试时无法找到$ref定义的文件路径问题

问题核心 #

Connexion v3解析OpenAPI规范里的$ref时，路径是基于主规范文件所在目录而非工作目录。但测试代码放在tests/目录下时，不同环境下的工作目录（CWD）可能混乱，加上硬编码路径或specification_dir设置时机错误，就会触发FileNotFoundError。

实操解决方案 #

1. 动态计算规范文件目录 #

不要写死路径，通过测试文件的位置推导项目根目录，确保specification_dir指向正确的OpenAPI规范存放路径。

示例代码（tests/test_server.py）：

import os
from pathlib import Path
import connexion

def prepare_server():
    # 获取当前测试文件的目录
    test_dir = Path(__file__).parent
    # 推导项目根目录（假设openAPI.yml在项目根的openapi/文件夹下）
    project_root = test_dir.parent
    spec_dir = project_root / "openapi"
    
    # 初始化Connexion应用
    app = connexion.FlaskApp(__name__, specification_dir=str(spec_dir))
    app.add_api("openAPI.yml", validate_responses=True)
    return app

2. 统一$ref的相对路径写法 #

确保openAPI.yml里的$ref路径是相对于主规范文件所在目录的，不要混用绝对路径或工作目录相对路径。

比如主规范文件在openapi/openAPI.yml，要引用同目录下schemas/user.yml的内容，写法应为：

components:
  schemas:
    User:
      $ref: schemas/user.yml#/components/schemas/User

3. 强制统一测试工作目录 #

在测试代码开头切换工作目录到项目根，避免不同环境下CWD不一致的问题：

import os
from pathlib import Path

# 切换到项目根目录
os.chdir(Path(__file__).parent.parent)

4. 验证路径有效性 #

在prepare_server里加临时打印，确认路径是否真的正确：

print(f"规范目录: {spec_dir}")
print(f"主规范文件存在: {(spec_dir / 'openAPI.yml').exists()}")
print(f"引用目标文件存在: {(spec_dir / 'schemas/user.yml').exists()}")

通过输出可以快速排查路径是否设置正确，避免假阳性错误。

关键总结 #

核心是消除路径依赖：

• 用动态计算代替硬编码路径，适配不同环境
• 让$ref路径始终相对于主规范文件所在目录
• 强制测试时的工作目录统一为项目根

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