API 调试器

API 调试器从服务端读取 Open API 元数据（operationId、方法、路径、参数），在控制台里选接口、填参数、按 AppSecret 计算签名并试调。它适合联调，不是生产网关；没有保存请求历史或环境变量管理。

概念​

  • 元数据来自 GET /api/admin/api-metadata，由服务端从 Open API IDL 派生，与文档同源。
  • 签名规则：Signature = hex(sha1(appSecret + nonce + timestamp))，请求头 App-Key/Nonce/Timestamp/Signature。
  • AppSecret 只在浏览器内存中使用，不落 localStorage；刷新页面需重新输入（或由控制台当前应用取用）。
  • 试调会真实写数据（如发消息、建群），请使用测试应用与测试用户。
不要在生产应用上随意试调

调试器发的是真实请求，可能产生消息、用户、群等数据；对生产应用执行写接口前请确认影响范围。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#debug（tab #debug：API 调试器）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 选择接口

    按 operationId 搜索，确认 method/path 与参数。

  2. 填参数与密钥

    按参数表填写 JSON；AppSecret 仅用于本地签名。

  3. 计算签名并发送

    控制台自动生成 Nonce/Timestamp 与 Signature；发送后查看 code/msg/data。

  4. 失败排查

    1018=签名错误、1019=时间戳过期、1020=Nonce 重放；先校准本机时间。

参数表​

操作方法与路径参数
接口元数据GET /api/admin/api-metadata—
OpenAPI 导出GET /openapi.json—
实际试调{basePath}{path}App-Key/Nonce/Timestamp/Signature + 接口参数

示例​

拉取接口元数据​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/api-metadata" \
  -H 'X-Admin-Secret: dev-admin'

# 只看单聊发布
curl -sS -X GET "http://127.0.0.1:8080/api/admin/api-metadata" \
  -H 'X-Admin-Secret: dev-admin' | jq '.data.operations[] | select(.operationId=="message.private.publish")'

手写一次签名调用​

Shell
# 应用服务器示例（Node）：timestamp 毫秒、nonce 随机串
node -e "const c=require('crypto');const s='<appSecret>',n='n1',t=Date.now();\
console.log(c.createHash('sha1').update(s+n+t).digest('hex'))"

常见问题​

调试器会保存请求历史吗？​

不会。刷新或切换 tab 后参数不保留；需要回归请用脚本或 OpenAPI 导出。

AppSecret 安全吗？​

只在本页内存中使用；但浏览器环境仍应使用测试应用，不要把生产密钥交给不可信机器。

为什么一直 1018？​

签名串顺序是 appSecret+nonce+timestamp，timestamp 为毫秒；确认没有被代理改写请求头。

能调管理 API 吗？​

调试器面向 Open API；管理 API 直接在「运营后台」或 curl 使用 X-Admin-Secret。

相关链接​