<kbd>和<samp>是HTML中语义化内联标签，分别表示用户输入与系统输出，用于API文档中提升可读性、自动化识别与无障碍访问；需合理搭配、避免嵌套、依赖原生语义而非CSS。

<kbd> 和 <samp> 是 HTML 中专用于呈现计算机交互内容的语义化内联标签，它们在 API 文档展示中不是装饰性元素，而是承担明确表达意图的功能角色：一个表示“用户输入”，一个表示“系统输出”。合理组合使用，能让接口调用示例更清晰、可读性更强，也利于自动化工具识别和辅助无障碍访问。

<kbd> 标签用于标记用户操作输入
它默认渲染为等宽字体（多数浏览器中与 <code> 类似），语义上强调这是“键盘输入”行为。在 API 文档中，适合包裹命令行指令、HTTP 方法名、请求头字段、参数键名或表单控件名称等需用户主动键入/选择的内容。

• 例如：<kbd>POST</kbd> 表示 HTTP 请求方法，<kbd>Authorization</kbd> 表示请求头字段名，<kbd>curl</kbd> 表示终端命令
• 不建议用它包裹整个命令字符串（如 curl -X POST ...），而应只包裹其中需用户理解或输入的关键部分

<samp> 标签用于标记系统返回样本
它同样采用等宽字体，但语义指向“程序输出”或“系统响应结果”，比如 JSON 响应体片段、错误消息文本、状态码、服务端日志行等。它的作用是把一段非代码块但需保持原始格式与语义的输出内容从普通段落中分离出来。

• 例如：<samp>{"code":200,"msg":"OK"}</samp> 表示典型成功响应；<samp>404 Not Found</samp> 表示 HTTP 状态行
• 注意：它不替代 <pre><code> 组合用于大段结构化代码，而是用于短小、上下文嵌入式的输出片段

两者搭配构建完整交互示意
当文档需要演示一次请求—响应过程时，<kbd> 和 <samp> 可在同一句或相邻行中协同出现，形成视觉与语义上的输入—输出对应关系：

• <p>发送 <kbd>GET</kbd> 请求到 <kbd>/api/v1/users</kbd>，预期返回 <samp>{"data":[{...}]}</samp>。</p>
• 在表格中：

  操作	说明
  Content-Type	请求头，值应为 application/json
  Accept	请求头，推荐设为 application/vnd.api+json

实际应用中的注意事项

• 避免嵌套使用（如 <kbd><samp>...</samp></kbd>），二者语义互斥，不应混用
• 不依赖 CSS 强制等宽——应靠原生语义标签本身实现，确保无样式时仍具可读性
• 若需高亮某段输出中的特定字段（如 status 字段），可在 <samp> 内部嵌套 <code> 或 <var>，但不宜再用 <kbd>
• 屏幕阅读器会依据这些标签播报不同提示（如 “keyboard input” 或 “sample output”），提升可访问性

不复杂但容易忽略