接口详情与在线调试

接口详情页是调用方了解和使用一个已发布接口的入口。页面提供接口文档、认证说明、多语言调用示例、签名工具和在线测试能力。

进入详情页

有三种方式进入接口详情页：

• 在 API Hub 点击接口卡片；
• 在 接口列表 → 已发布 点击「文档」；
• 直接访问 /doc?aid={apiId}&env={envCode}。

env 决定页面展示哪个环境的地址和参数快照。API Hub 默认携带 prod；从接口列表进入时可指定其他环境。环境不存在、接口未在该环境上线或已下线时，页面无法加载接口信息。

页面结构

页面顶部是基本信息区，下方只有两个页签：

页签	内容
接口文档	请求/响应参数、认证说明、调用示例
在线测试	在浏览器中直接向真实环境发起调用并查看响应

当前版本没有独立的 MCP 页签。接口若同时以 MCP 协议发布，接入方式请参考 MCP 接入，MCP 客户端配置可从应用凭证的「MCP 配置」中获取。

基本信息

信息	说明
接口名称	发布时使用的接口名称
接口 ID	当前接口源的 ID
认证方式	免认证 / AppKey / AppKey + 签名 / OAuth2 客户端凭证 / 企业 IdP JWT
上线时间	当前环境快照的上线时间
版本号	接口基本信息中的版本号
接口地址	当前环境地址 + 接口路径，可一键复制
接口描述	发布时的接口描述

如果当前环境没有配置访问地址，接口地址位置会显示「当前环境未配置访问地址」，此时在线测试不可用。

Mock 地址

当详情页处于 dev 环境且接口存在启用中的 Mock 规则时，会额外展示一行 Mock 地址：

{环境地址}/mock/dev{接口路径}

Mock 地址只对开发联调开放，并且请求必须携带有效的 X-AppKey。Mock 规则、延迟与响应配置见 接口测试与 Mock。

接口文档页签

请求参数

参数按位置分组展示，覆盖 header、query、path、body 四类。每个参数包含名称、类型、是否必填、示例值和说明；对象与数组类参数按层级展开。

响应参数

响应参数展示字段名、类型、说明和示例值。示例值来自接口定义中的「示例值」配置，未配置时按类型生成默认值。

认证请求头

不同认证方式需要携带的请求头不同：

认证方式	请求头	说明
免认证	无	接口公开可调用，但仍可能受 IP、流控等治理规则约束
AppKey	X-AppKey	仅校验应用身份，不校验签名
AppKey + 签名	X-AppKey、X-Timestamp、X-Nonce、X-Sign	默认使用 SM3 摘要与 HMAC-SM3 签名
OAuth2 客户端凭证	Authorization	值为 Bearer <access_token>，token 由 /oauth2/token 换取
企业 IdP JWT	Authorization	值为 Bearer <enterprise_token>，token 由企业 IdP 签发，不需要 AppKey 与签名

签名规则：

签名串 = HTTP_METHOD + "_" + API_PATH + "_" + AppKey + "_" + Timestamp + "_" + Nonce + "_" + 载荷摘要
载荷摘要 = SM3(原始 query 串 + 0x0A + 请求体)
X-Sign = HMAC-SM3(AppSecret, 签名串)

• query 串不含开头的 ?，必须与实际发送内容逐字一致；
• GET、HEAD 请求没有请求体，载荷中的请求体部分为空；
• 时间戳为毫秒级，允许窗口为 10 分钟；
• nonce 在 10 分钟内不可重复；
• 默认算法为 SM3，请求头 X-Algorithm: HmacSHA256 可切换为 HMAC-SHA256。

完整的安全规则、错误码和多种语言的签名实现见 签名认证指南。

在线签名工具

app_secret 认证接口在认证说明旁提供「在线签名」入口。填写 AppKey、AppSecret、原始 query 串和请求体后，工具会自动生成时间戳、nonce、载荷摘要和 X-Sign，可复制到调试工具中使用。签名工具默认使用 SM3 算法。

OAuth2 接入指引

oauth2 认证接口在相同位置显示「OAuth2 接入指引」，说明如何用应用凭证换取 token：

POST {环境访问地址}/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={AppKey}&client_secret={AppSecret}

• client_id 为应用 AppKey，client_secret 为应用 AppSecret；
• 成功返回 access_token、token_type、expires_in、scope，默认有效期 30 分钟；
• 调用接口时携带 Authorization: Bearer <access_token>，无需再计算签名；
• AppSecret 只在换取 token 时传输一次，请始终在服务端调用并使用 HTTPS。

完整的参数、错误与多语言示例见 OAuth2 客户端凭证认证。

JWT 接入指引

jwt 认证接口在相同位置显示「JWT 接入指引」，说明如何用企业 IdP 签发的 token 调用：

Authorization: Bearer {enterprise_idp_access_token}

• token 由企业 IdP（Keycloak、Azure AD 等）签发，平台只验签，不提供换取接口；
• 请求只需要 Authorization，不需要 X-AppKey、X-Timestamp、X-Nonce、X-Sign；
• 调用方需要在凭证中绑定 (IdP, subject)，平台据此识别应用；
• 认证失败返回 HTTP 401/403/503 + WWW-Authenticate，而不是 HTTP 200 业务码。

完整的配置、claims 要求与多语言示例见 JWT 企业 IdP 认证。

调用示例

接口文档提供 cURL、Java、Go、PHP、Python、JavaScript 六种语言的调用示例，示例中的地址取自当前环境。

示例不包含签名与 token 换取

代码示例只演示请求结构和参数，不会自动计算 X-Sign，也不会调用 token 端点。app_secret 认证的接口必须按签名规则自行实现签名，或使用上面的在线签名工具生成后再调用；oauth2 认证的接口需先换取 access_token 再放入 Authorization 请求头；jwt 认证的接口需先向企业 IdP 获取 token。

在线测试页签

在线测试由浏览器直接向接口地址发起 fetch 请求，不经过平台后端代理。

使用步骤

1. 在参数表中填写 header、query、path 和 JSON 请求体；
2. app_secret 认证的接口填写 AppKey 与 AppSecret，发送时会自动生成 X-Timestamp、X-Nonce 和 X-Sign；
3. oauth2 认证的接口填写 AppKey 与 AppSecret 后点击「获取 Token」，再点击「发送」；
4. jwt 认证的接口粘贴企业 IdP 签发的 access token（仅保存在页面内存，切换接口后清空）；
5. 点击「发送」；
6. 在响应区查看 HTTP 状态码、响应时间、响应大小和响应内容。

行为说明

• 页面会根据接口参数定义预填参数行，必填项和默认值直接带入；
• app_key 认证会预填 X-AppKey 请求头，需要填写应用凭证；
• oauth2 认证会向与接口地址同源的 /oauth2/token 换取 token，并自动写入 Authorization: Bearer <access_token> 请求头；token 在 expires_in - 30 秒内复用，返回 40025 / 40026 时自动重新换取并重试一次；
• jwt 认证只向请求注入 Authorization: Bearer <enterprise_token>，不会注入 AppKey；响应区额外展示 WWW-Authenticate；
• app_secret 认证每次发送都会重新生成时间戳和 nonce，签名基于实际发送的 query 与请求体计算；
• 请求体只支持 JSON 模式，非法 JSON 会在发送前被拦截；
• 响应若为 JSON 会格式化展示，否则按文本展示；
• 返回 HTML 时会给出提示，通常说明环境地址配置错误，请求打到了前端页面。

常见失败原因

现象	可能原因
提示填写认证参数	app_secret / oauth2 接口未填写 AppKey 或 AppSecret；jwt 接口未填写 token
获取 Token 失败 invalid_client	AppKey/AppSecret 不属于同一应用、应用已禁用，或来源 IP 不在应用白名单
浏览器跨域错误	目标环境未允许当前站点跨域，或网关 CORS 配置未覆盖该来源
混合内容被拦截	文档站点为 HTTPS，而环境地址为 HTTP
返回 HTML	环境访问地址未配置或配置成了前端站点
401 / 40013	凭证无效、签名错误、时间戳或 nonce 校验失败
40024 / 40025	OAuth2 接口未携带 Bearer token，或 token 已过期、无效
401 / 40029（jwt）	企业 IdP token 无效、过期、受众不符或签名校验失败
403 / 40031（jwt）	token 主体未绑定任何应用，或绑定关系不一致
503 / 40030（jwt）	JWT 功能未开启，或 IdP / JWKS 暂不可用
403 / 40018	请求来源 IP 不在应用白名单内
429 / 40023	订阅日调用量配额已用完

订阅入口

需要授权的接口在页面顶部显示「订阅申请」按钮：

• 免认证接口不显示申请按钮；
• 已有审批中的申请时，按钮显示「审批中」并禁用；
• 申请通过后，应用凭证即可调用该接口。

申请字段与审批流程见 订阅与审批。

相关文档

• API 目录与调用申请
• 应用凭证与授权
• 订阅与审批
• 签名认证指南
• OAuth2 客户端凭证认证
• JWT 企业 IdP 认证
• MCP 接入