Clarify

API 文档

这篇文档合并说明 Clarify 的 OpenAPI 能力：生成完整 API Reference、在 MDX 指南中嵌入单个接口、组织产品级 API 文档，以及把原始规范输出给 AI 工具。

Clarify 把 OpenAPI 规范当作一等内容源。规范负责接口事实，MDX 负责解释业务流程。

你可以用它做什么

目标推荐能力
发布完整接口列表.openapi.json / .openapi.yaml 自动生成 API Reference
在教程中展示一个接口OpenApiOperation
给完整 Reference 添加前后说明OpenApiDocument
按业务域拆分 API 页面filter.tags 从同一份规范生成多个分组页面
让开发者快速试调用自动展示 server、server variables、认证输入、请求体和响应示例
复制可运行请求代码根据规范生成多语言、多客户端代码示例
让 AI / LLM 读取原始规范构建输出中的 .openapi.* 原始文件和 llms.txt
多语言站点维护 API 文档把规范放入语言目录，例如 source/zh-CN/api.openapi.json

OpenAPI 页面不只是静态字段表。Clarify 会把规范转成面向开发者的交互式接口文档：用户可以选择服务器、填写 server variables、选择认证方式、切换请求和响应示例，并复制不同语言的请求代码。

最小示例

把 OpenAPI 文件放入内容目录：

source/
├── index.mdx
└── api.openapi.json

Clarify 会生成：

产物说明
/api完整 API Reference 页面
/api.openapi.json原始 OpenAPI 规范输出
llms.txt 中的 OpenAPI 链接方便 AI 工具发现和读取

如果你显式维护侧边栏，在 tabs 中加入：

{
  openapi: 'api.openapi.json',
  title: 'API Reference',
  icon: 'FileJson2',
}

你也可以通过 filter.tags 从同一个 OpenAPI 文件发布多个页面。过滤页面只会展示 OpenAPI operation.tags 中至少命中一个指定 tag 的接口：

{
  openapi: 'api.openapi.json',
  title: 'Projects API',
  icon: 'FolderKanban',
  filter: {
    tags: ['Projects'],
  },
}

例如 api.openapi.json 配置 filter.tags: ['Projects'] 后，页面路由为 /api/projects。tag 会被转成小写 kebab-case；多个 tag 会按配置顺序拼接，例如 ['Admin Users', 'Billing'] 会生成 /api/admin-users-billing。

规范格式与路由

支持 OpenAPI 3.0 / 3.1，文件扩展名：

格式示例路由
JSONapi.openapi.json/api
YAMLbilling.openapi.yaml/billing
YAML 简写admin.openapi.yml/admin

启用 i18n 时，OpenAPI 文件也遵循语言目录规则。默认语言不带 locale 前缀，非默认语言会带上 locale 前缀：

source/
├── zh-CN/
│   └── api.openapi.json  → /api
└── en-US/
    └── api.openapi.json  → /en-US/api

因此在中文页面中嵌入接口时通常使用 specPath="/api"；在英文页面中嵌入同一规范时通常使用 specPath="/en-US/api"。

构建时 Clarify 会使用 @apidevtools/swagger-parser 解析并 dereference 规范。规范无效时，生产构建会失败，避免发布过期或错误的接口文档。

在指南中嵌入接口

产品级 API 文档不应该只有 Reference。推荐围绕真实任务写指南，并在关键步骤旁嵌入对应 operation。

# 认证

使用访问令牌调用受保护接口。令牌过期后，重新创建会话。

<OpenApiOperation specPath="/api" path="/sessions" method="post" />

OpenApiOperation 参数：

参数说明
specPathOpenAPI 路由，不写 .openapi.json 后缀，例如 /api
pathOpenAPI paths 中的路径，必须完全一致
methodHTTP 方法，建议小写，例如 get、post、patch

如果要在 MDX 中插入完整 Reference，可以使用：

<OpenApiDocument specPath="/api" />

交互式接口面板

OpenApiOperation 和完整 API Reference 会根据规范自动生成接口面板。规范越完整，页面上的交互越有用：

能力来源用户看到什么
Server 选择servers可以在不同环境或域名之间切换
Server variablesservers[].variables可以填写或选择变量值，例如 region、version
认证输入components.securitySchemes + security根据 API Key、Bearer、Basic、OAuth 等方案生成占位输入
参数说明parameters路径、查询、Header 参数分组展示
请求体示例requestBody.content.*.example/examples/schema可以切换 media type 和示例
响应示例responses展示不同状态码和响应体
复制请求代码OpenAPI 规范 + 当前选择一键复制当前接口的请求示例

Clarify 会为常见语言和客户端生成请求代码，包括 cURL、Wget、HTTPie、JavaScript/TypeScript Fetch、Axios、ofetch、Python Requests、HTTPX、aiohttp、Go、Java、C#、PHP、Ruby、Rust、Swift、Kotlin 和 PowerShell 等。

推荐 API 文档结构

source/
├── guides/
│   ├── authentication.mdx
│   ├── pagination.mdx
│   └── webhooks.mdx
├── api.openapi.json
└── index.mdx

写作分工：

角色负责内容
后端 / API 平台OpenAPI 规范、schema、响应码、认证方式
技术写作指南结构、调用流程、错误解释
前端 / SDK示例代码、SDK 行为、真实集成场景
产品 / 开发者体验信息架构、命名、读者任务路径

发布前检查：

  • OpenAPI 文件能被构建成功解析。
  • 侧边栏中有清晰的 API Reference 入口。
  • 关键业务流程有指南，而不只是接口列表。
  • 示例请求和响应没有测试数据泄漏。
  • 错误响应有明确说明。
  • llms.txt 能列出原始 OpenAPI 规范链接。

内容质量建议

API Reference 的质量主要取决于 OpenAPI 规范本身。建议至少补齐：

  • info.title、info.version、info.description
  • servers，如有变量则补齐 servers[].variables
  • tags，用于导航分组和 filter.tags 拆分页面
  • 每个 operation 的 summary 和 description
  • 参数的 description、schema、example 或 examples
  • 请求体和响应的 media type、example、examples 或可推导示例的 schema
  • 主要响应码和错误响应
  • 复用的 components.schemas
  • 认证方式 components.securitySchemes 和 operation/security requirement

常见问题

API 页面没有出现在侧边栏？

如果显式配置了 tabs[].pages，Clarify 不会自动把所有文件插入侧边栏。需要手动添加 openapi 条目。

OpenAPI spec not found？

检查：

  • OpenAPI 文件是否在 source 下。
  • 文件名是否使用 .openapi.json / .openapi.yaml / .openapi.yml。
  • specPath 是否写的是路由，而不是文件名。

Endpoint not found？

检查 path 是否和 OpenAPI paths 键完全一致，路径参数是否使用 {id} 形式，method 是否存在于该路径下。