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 函数以同批交付类型和源码为准。

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

使用 OpenAPI

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

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 请求数不一致时停止发布，先重新生成和审计。