agent-fox/docs/getting-started/import-api-docs.md

导入 API 文档

AgentFox 支持导入 OpenAPI 3.x 和 Swagger 2.0 格式的 API 文档。

导入方式

方式一：从 URL 导入

1. 在控制台点击「导入 API 文档」按钮
2. 选择「从 URL」标签
3. 粘贴 OpenAPI 文档的 URL
4. 点击「导入」

提示：支持 localhost 和内网地址。AgentFox 会先尝试在浏览器端直接获取，如果遇到 CORS 限制，会自动通过服务端代理获取。

方式二：上传文件

1. 在控制台点击「导入 API 文档」按钮
2. 选择「上传文件」标签
3. 拖放文件到上传区域，或点击选择文件
4. 支持 .json、.yaml、.yml 格式
5. 点击「导入」

支持的格式

格式	版本	说明
OpenAPI	3.0 / 3.1	推荐，功能最完整
Swagger	2.0	完整支持，自动转换 body 参数为 requestBody 格式

支持的文件类型：

• JSON（.json）
• YAML（.yaml / .yml）

导入后会发生什么？

1. 验证：AgentFox 使用 swagger-parser 验证文档格式
2. 解引用：所有 $ref 引用被自动展开
3. 分组：端点按 OpenAPI tags 或 URL 路径前缀自动分组为模块
4. 索引：所有端点的参数、请求体、响应格式被索引存储

导入成功后，你将看到：

• 项目名称（来自文档的 info.title）
• 解析出的模块数量
• 解析出的端点数量

示例：导入 Petstore API

你可以用以下公开的 OpenAPI 文档来测试：

https://petstore3.swagger.io/api/v3/openapi.json

导入后将创建包含多个模块（pet、store、user）和对应端点的项目。

下一步

文档导入成功后，接下来 生成 API Key 以启用 MCP 服务。