# OpenAPI、Postman 与客户端资产

正式客户包的公开契约资产位于 `Documentation/SKILL/akstream-next-integration/references`：

- `openapi.json`
- `postman-collection.json`
- `postman-environment.json`

当前随版第三方 Skill 提供 1.0.0.169 的公开契约，共 626 个公开操作，覆盖完整业务及管理 API；精确字段和权限请读取同版资产并核对部署版本。RTC SDK 函数以同批交付类型和源码为准。

```mermaid
flowchart LR
    A[同版本 OpenAPI] --> B[Swagger / 代码生成]
    A --> C[Postman 集合]
    A --> D[字段与接口索引]
    B --> E[自动契约测试]
    C --> E
    D --> E
```

## 使用 OpenAPI

为目标语言生成客户端时固定输入文件和 AKStream.Next 版本。例如：

```bash
npx @openapitools/openapi-generator-cli generate \
  -i Documentation/SKILL/akstream-next-integration/references/openapi.json \
  -g typescript-fetch \
  -o generated/typescript
```

生成 SDK 后仍需手工封装异步命令、文件流、Range、SDP、WebSocket、幂等与错误原文。代码生成器不能理解业务终态。

## 使用 Postman

导入 Collection 与 Environment 后，只在 Postman 的 secret/current value 中设置 `baseUrl` 与 Token，不把真实值导出或提交。

每个写接口的测试应：

- 检查 2xx/202；
- 保存返回资源或命令 ID；
- 提供后续状态查询；
- 保留 TraceId 和原始错误；
- 清理本次创建的测试资源。

文件、WebSocket 和 SDP 应另做专门测试，不要强行用普通 JSON 请求替代。

## 契约升级

升级前对旧版和新版 OpenAPI 做差异检查，至少关注：

- 删除或改名的路径与字段；
- 新增必填字段；
- null/空字符串语义；
- 状态枚举新增；
- 权限变化；
- Content-Type 和文件行为；
- 分页默认与上限；
- 异步返回从同步结果变为 command/session。

客户端应忽略未知响应字段并保留 unknown 状态，但不能忽略新增必填输入和权限要求。

## Swagger 访问边界

线上 Swagger/Knife4j 与 OpenAPI JSON 需要交互式 WebUI 会话。API Token 不能用来枚举文档入口。CI、SDK 与无人值守测试使用随版本保存的资产。

## 发布检查

生成资产必须与同一 commit、同一产品版本的服务对应。OpenAPI、接口索引、模型索引与 Postman 请求数不一致时停止发布，先重新生成和审计。