60 lines
1.7 KiB
Markdown
60 lines
1.7 KiB
Markdown
# 导入 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](generate-api-key.md) 以启用 MCP 服务。
|