JetBrains Aqua调用本地OpenAPI v3接口提示Failed to Fetch求助

安全阿岳

2026-8-6

解决JetBrains Aqua OpenAPI「Try it out」请求失败问题

以下是针对该问题的排查和解决步骤：

检查OpenAPI规范的服务器URL配置
确认规范中servers字段指向的本地地址是否准确。比如API运行在http://localhost:8080，需确保servers数组的url配置无误，避免使用未解析的占位符或错误的端口/域名。示例配置：
```
servers:
  - url: http://localhost:8080
```
验证API的CORS设置
尽管curl、浏览器和Aqua内置HTTP Client能正常访问，但OpenAPI GUI的请求上下文可能触发CORS限制。临时为API服务器添加宽松的CORS响应头调试：
```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```
问题解决后再调整为符合生产要求的严格规则。
排查Aqua的代理设置
打开Aqua设置（File > Settings），搜索「HTTP Proxy」，确认是否开启了不必要的代理。若本地API无需代理，切换到「No proxy」模式，或把本地地址加入代理例外列表。
重新导入OpenAPI规范
若Aqua缓存了旧的规范数据，可能导致请求异常。删除当前导入的OpenAPI配置，重新导入最新的规范文件或URL，确保界面加载的是最新定义。
检查自动填充的请求头
Aqua的「Try it out」可能自动填充默认请求头（如Host、Content-Type），若与API预期不符会导致请求失败。手动检查请求面板的所有头信息，移除或修改不符合要求的字段后重试。