企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

## 六、交互式文档：让开发者不离开浏览器就能调 API ### 6.1 "Try It" 功能的核心特征 - **预认证（Pre-authenticated）**：自动使用开发者的沙箱 Key - **预填充（Pre-filled）**：填入可工作的示例数据 - **参数可编辑（Editable）**：请求参数可直接修改 - **真实响应（Real responses）**：返回真实的 API 响应而非 mock - **可导出（Copy as cURL/code）**：一键复制为 cURL 或代码 SKILL.md 给出了一个可直接参考的 HTML 结构示意： ```html <div class="api-explorer"> <h3>Try it: Send a Message</h3> <div class="request-editor"> <label>To Phone Number</label> <input type="text" value="+15551234567" /> <label>Message Body</label> <textarea>Hello from the API Explorer!</textarea> <button onclick="sendRequest()">Send Request</button> </div> <div class="response-viewer"> <h4>Response</h4> <pre><code id="response"></code></pre> </div> </div>

6.2 可选工具

基于 OpenAPI 的现成方案：Swagger UI、Redoc、Stoplight Elements；自定义平台：ReadMe.io、Postman Published Docs、自定义 React 组件。

6.3 交互式教程：不止单请求

把多个"Try It"组件串成带状态传递的分步教程，效果远超孤立的单请求示例：

## Interactive Tutorial: Send Your First Message ### Step 1: Check your balance <api-explorer endpoint="GET /account/balance" /> ### Step 2: Send a message <api-explorer endpoint="POST /messages" body='{"to": "+15551234567", "body": "Hello!"}' /> ### Step 3: Check message status <api-explorer endpoint="GET /messages/{id}" params='{"id": "{{previous.id}}"}' />

注意 Step 3 中{{previous.id}}这种前一步结果引用的写法——它让教程从"演示"升级为"可完成的真实任务"，这正是交互式文档的进阶形态。

七、常见失败点：开发者卡在哪、为什么、怎么修

技能给出了一个非常有价值的统计分布（基于该技能上游实践经验的总结，具体数值需结合自有数据验证）：

7.1 失败点埋点

要拿到上述分布，需要在 API 网关侧埋点，技能给出的示例如下：

// Instrument error events api.on('request_error', (error, request) => { analytics.track('api_error', { error_type: error.type, error_code: error.code, endpoint: request.endpoint, time_since_signup: timeSinceSignup(), is_first_call: isFirstCall() }); });

其中time_since_signup（距注册时间）与is_first_call（是否首次调用）两个字段，专门用于识别"新手在首次调用时犯错"的场景——这正是上手优化要优先解决的。

7.2 可恢复的错误设计

错误信息不仅要指出问题，还要给出恢复路径。技能给出了带recovery字段的错误响应结构：

{ "error": { "type": "authentication_error", "message": "Invalid API key provided", "code": "invalid_api_key", "recovery": { "steps": [ "Check that your API key starts with 'sk_test_' or 'sk_live_'", "Ensure there are no extra spaces or newlines", "Generate a new key at https://dashboard.example.com/keys" ], "docs": "https://docs.example.com/authentication", "support": "https://support.example.com/auth-issues" } } }

• AI 技能
• AI 插件
• 人工智能