API Document Management and API Test
概述
正确管理 API 文档对于开发者入职、测试和集成至关重要。APIM 允许您附加 OpenAPI 规范或手动定义文档，然后立即在界面中测试 API。本教程展示了如何上传/编辑文档并使用示例配置对已部署的 API 进行测试。
先决条件
您需要：
- 一个已部署的 API 版本（例如，user-service-api v1.0）
- 具有编辑者或管理员权限的 APIM 控制台访问权限
- OpenAPI 规范文件或手动编写的 API 定义详细信息
分步教程
步骤 1. 打开 API 版本详细信息页面
- 转到 API 管理
- 选择 user-service-api
- 选择版本 v1.0
步骤 2. 上传或编辑 API 文档
您有两个选项：
选项 A：上传 OpenAPI (YAML/JSON)
- 点击导入
- 选择并上传您的 OpenAPI 3.0 文件（例如，user-service-v1.yaml）
- 系统解析并更新所有端点和描述
选项 B：手动 API 定义
如果没有可用的 OpenAPI 文件：
- 点击文档选项卡下的编辑
- 手动添加详细信息： | 字段 | 示例 | | --- | --- | | 摘要 | 用户登录端点 | | 方法 | POST | | 路径 | /login | | 请求体 | 包含用户名和密码的 JSON | | 响应 | 200 OK + JSON 主体 |
完成后点击保存。
步骤 3. 使用内置测试器测试 API
导航到 API 版本详细信息页面中的测试选项卡：
| 字段 | 值 |
|---|---|
| 目标方法 | POST |
| 路径 | /v1/login |
| 头部 | Content-Type: application/json |
主体示例：
{
"username": "jane.doe",
"password": "test1234"
}
点击发送请求
步骤 4. 审查测试结果
预期响应：
{
"userId": "12345",
"token": "eyJhbGciOi..."
}
控制台将显示：
- HTTP 状态码（例如，200 OK）
- 耗时
- 请求和响应体
常见问题与故障排除
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 无效的 OpenAPI 文件 | 语法错误或不支持的字段 | 使用 Swagger Editor 进行验证 |
| 测试中没有响应 | 路径错误或缺少后端 | 仔细检查网关路由路径和后端健康状况 |
| 401 未授权 | 缺少 API 密钥或身份验证策略 | 设置 Authorization 头或暂时禁用身份验证 |
| 415 不支持的媒体类型 | 缺少或错误的 Content-Type | 对于请求体使用 application/json |
最佳实践
- 始终上传经过验证的 OpenAPI 规范以确保文档准确
- 为每个端点添加示例请求/响应
- 在与外部消费者共享 API 之前使用内置测试工具
- 记录错误响应（4xx/5xx），而不仅仅是成功案例
- 保持 API 文档与 API 生命周期版本一致