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生命周期版本一致