Fumadocs OpenAPI 中空 servers 数组处理机制的探讨与优化

背景介绍

在 API 文档工具 Fumadocs OpenAPI 的最新版本 1.1.0 中，开发团队发现了一个与 OpenAPI 规范实现差异的问题。当开发者在 swagger.json 文件中提供一个空的 servers 数组时，系统会默认使用 example.com 作为主机地址，这与上游 OpenAPI 规范的处理方式存在不一致。

问题分析

根据 OpenAPI 3.0 规范，当 servers 数组未提供或为空时，服务器 URL 应默认为 /，并应相对于托管 OpenAPI 定义文件的服务器的位置进行解析。然而在 Fumadocs OpenAPI 的当前实现中，代码会强制将空 servers 数组转换为指向 example.com 的默认配置。

这种差异主要体现在两个关键组件中：

1. 在 api-page.tsx 文件中，当检测到空 servers 数组时会硬编码返回 example.com
2. 在 CodeExample 组件中，默认使用 / 作为基础路径，而其他组件如 playground 则使用 window.location.origin

技术实现考量

Fumadocs OpenAPI 作为一个主要进行服务端渲染的工具，在处理 OpenAPI 模式时面临两种场景：

1. 通过 URL 传递的 OpenAPI 模式 - 支持 / 作为服务器 URL
2. 通过文件路径传递的模式 - / 在这种情况下没有实际意义

项目维护者指出，虽然可以支持第一种情况，但出于对文件路径模式兼容性的考虑，可能保持现有行为更为稳妥。

解决方案探讨

经过社区讨论，提出了几种可能的改进方案：

1. 基础方案：

   • 修改 CodeExample 组件，使其默认使用 window.location.origin 而非 /
   • 调整 api-page.ts/getContext() 逻辑，移除 example.com 硬编码

2. 渐进式方案：

   • 引入 useBroswerHostAsDefault 全局标志，允许开发者选择是否启用新行为
   • 保持对文件路径模式的支持，同时为 URL 模式提供规范兼容

3. 临时解决方案： 开发者可以通过 pnpm patch 机制临时修改构建产物，实现规范兼容行为

技术决策与影响

最终技术决策需要考虑以下因素：

• 服务端渲染兼容性：window 对象在服务端不可用
• 模式来源多样性：需要同时支持 URL 和文件路径两种模式
• 开发者体验：保持行为一致性，避免意外行为变化

一个可行的折中方案是：基于 OpenAPI 模式的来源（URL 或文件路径）智能选择默认服务器地址，同时提供显式配置选项供开发者覆盖默认行为。

总结

Fumadocs OpenAPI 在处理空 servers 数组时的行为优化，反映了开源项目中规范实现与实际应用场景之间的平衡考量。这个问题不仅涉及技术实现细节，也体现了良好开发者体验与规范兼容性之间的权衡。开发团队需要在保持现有功能稳定性的同时，逐步向规范靠拢，这需要谨慎的技术决策和周密的实现方案。