Komga项目Swagger接口请求报错问题分析与解决

问题背景

在Komga 1.20版本中，用户在使用Swagger UI进行API测试时遇到了一个普遍性问题。当用户登录后尝试执行任何API请求时，系统会返回"Undocumented TypeError: NetworkError when attempting to fetch resource"错误，导致所有API请求都无法正常执行。

问题现象分析

通过用户报告和日志分析，我们发现这个问题具有以下特征：

1. 仅在升级到1.20版本后出现
2. 影响所有API请求
3. 错误信息表明存在网络连接问题
4. 请求似乎被重定向到了错误的本地地址

根本原因

经过技术分析，问题的根源在于Komga 1.20版本中OpenAPI配置的实现方式。项目中的OpenAPI配置同时服务于两个用途：

1. API文档导出功能
2. 运行实例中的Swagger UI展示

在1.20版本中，虽然添加了服务器配置(servers)，但这些配置本不应该在Swagger UI运行时被使用。由于配置共享，导致Swagger UI错误地尝试使用这些服务器配置，而非当前运行实例的实际地址。

技术细节

在OpenAPI规范中，servers数组用于定义API的目标服务器。当这个配置被错误地应用到Swagger UI时，会导致以下问题：

1. Swagger UI不再使用当前页面的主机和端口
2. 转而尝试连接到配置中指定的服务器地址(如localhost或localhost:8080)
3. 由于这些地址在实际部署环境中通常不可达，导致网络错误

解决方案

该问题已在Komga 1.21.0版本中得到修复。修复方案主要包括：

1. 分离OpenAPI配置的不同用途
2. 确保Swagger UI运行时使用正确的当前实例地址
3. 保留API文档导出功能所需的服务器配置

用户影响

对于遇到此问题的用户，建议采取以下措施：

1. 升级到Komga 1.21.0或更高版本
2. 升级后无需额外配置，Swagger UI将自动使用正确的服务器地址
3. 所有API请求将恢复正常工作

总结

这个案例展示了在API文档工具实现中配置共享可能带来的问题。Komga团队通过区分不同使用场景下的配置需求，有效地解决了Swagger UI的请求错误问题。对于开发者而言，这也提醒我们在设计配置系统时需要考虑不同使用场景的特殊需求。