Hasura GraphQL Engine 中 OpenAPI 连接器文件路径配置问题解析

在使用 Hasura GraphQL Engine 的 OpenAPI 连接器时，开发者可能会遇到一个常见的配置问题：当尝试通过本地文件提供 OpenAPI 规范文档时，连接器无法正确加载文档并抛出错误。本文将深入分析这一问题的根源及解决方案。

问题现象

开发者在初始化 OpenAPI 连接器后，尝试执行数据源内省操作时遇到以下错误：

Cannot create property 'info' on string 'error while fetching data from URL ""'

这表明连接器尝试从一个空URL获取OpenAPI规范文档失败，而实际上开发者期望的是从本地文件加载。

问题根源分析

OpenAPI 连接器默认设计为从两种来源获取规范文档：

1. 通过 URL 远程获取（当配置了 NDC_OAS_DOCUMENT_URI 环境变量为有效URL时）
2. 从容器内固定路径 /etc/connector/swagger.json 读取本地文件

当开发者将 NDC_OAS_DOCUMENT_URI 设置为本地文件路径（如 ./trilium.yaml）时，连接器不会自动将该文件挂载到容器内，导致连接器既找不到URL资源，也找不到预期的本地文件。

解决方案

要正确使用本地 OpenAPI 规范文件，开发者需要采取以下步骤：

1. 文件命名规范：确保本地文件命名为 swagger.json（即使原始文件是YAML格式，也需要转换为JSON格式）

2. 容器挂载路径：必须将文件挂载到容器内的固定路径 /etc/connector/ 下

3. 环境变量配置：可以不设置 NDC_OAS_DOCUMENT_URI 环境变量，让连接器使用默认路径

实现细节

对于使用 Docker Compose 的部署方式，需要在 compose 文件中添加 volume 挂载配置：

volumes:
  - ./path/to/your/swagger.json:/etc/connector/swagger.json

这样配置后，连接器就能在容器启动时找到并正确加载 OpenAPI 规范文档。

最佳实践建议

1. 对于 YAML 格式的 OpenAPI 规范，建议先转换为 JSON 格式
2. 在开发环境中，可以使用实时重载功能，在文件变更时自动更新连接器
3. 生产环境中，建议将规范文件打包进自定义镜像，而非通过挂载方式

通过正确理解 OpenAPI 连接器的工作机制和文件加载逻辑，开发者可以避免这类配置问题，顺利实现 REST API 到 GraphQL 的转换。