OpenAPI 嵌入使用说明

Clarify 不只会把 .openapi.json / .openapi.yaml 渲染成完整 API Reference，也允许你在 MDX 指南里嵌入单个接口或完整 Reference。这样可以把“接口事实”和“业务流程说明”放在同一个页面里。

适用场景

场景	推荐方式
在教程中解释某一步调用哪个接口	`OpenApiOperation`
在专题页中展示某个核心接口的完整参数和响应	`OpenApiOperation`
在 MDX 页面里补充说明后再展示完整 API Reference	`OpenApiDocument`
让读者同时看到业务说明和机器可读规范	MDX 说明 + OpenAPI 嵌入 + 原始规范链接

准备 OpenAPI 文件

把规范放在当前语言目录下，例如：

source/
└── zh-CN/
    ├── api.openapi.json
    └── openapi/
        └── embedding.mdx

文件名决定 Reference 路由：

文件	Reference 路由	原始规范输出
`api.openapi.json`	`/api`	`/api.openapi.json`
`billing.openapi.yaml`	`/billing`	`/billing.openapi.yaml`
`admin.openapi.yml`	`/admin`	`/admin.openapi.yml`

在多语言站点中，英文规范可以放在 source/en-US/api.openapi.json，中文规范放在 source/zh-CN/api.openapi.json。Clarify 会按当前语言读取对应文件；缺失时再按 i18n fallback 策略处理。

嵌入单个接口

使用 OpenApiOperation：

<OpenApiOperation specPath="/api" path="/examples/basic-request" method="get" />

参数说明：

参数	必填	说明
`specPath`	是	OpenAPI Reference 的路由，不写 `.openapi.json` 后缀，例如 `/api`
`path`	是	OpenAPI `paths` 中的路径，必须和规范完全一致，例如 `/examples/path-parameters/{pageId}`
`method`	是	HTTP 方法，建议小写，例如 `get`、`post`、`patch`

渲染效果：

GET

/examples/basic-request

基础的请求结构

演示路径级 Header、查询参数、示例、响应 Header、链接和安全配置覆盖。

查询参数

Name
cursor
Type
string
Description
操作参数。
Name
limit
Type
integer
Description
操作参数。
Name
status
Type
draft | published | archived
Description
按发布状态筛选。
Name
include
Type
authors | assets | children[]
Description
需要一并返回的关联资源。

请求头

Name
X-Trace-Id
Type
string
Description
请求链路中透传的可选 Trace ID。

响应

Name
200
Type
object
Description
页面集合。
Name
400
Type
object
Description
请求无效。
Name
401
Description
凭证缺失或无效。
Name
default
Type
object
Description
未知错误。

请求

GET/examples/basic-request

curl 'https://api.clarify.local/v1/examples/basic-request?cursor={cursor}&limit={limit}&status={status}&include={include}' \
  --header 'Authorization: Bearer {token}' \
  --header 'Accept: application/json'

响应

application/json

{
  "data": [
    {
      "id": "pg_123",
      "title": "Getting Started",
      "slug": "getting-started",
      "status": "published",
      "content": "# Getting Started",
      "frontmatter": {},
      "parentId": null,
      "createdAt": "2026-06-17T12:00:00Z",
      "updatedAt": "2026-06-17T12:00:00Z",
      "links": []
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": false
  }
}

嵌入复杂请求接口

当接口包含多种请求体、多个 examples、多状态码响应或回调时，也可以直接嵌入同一个组件。下面的 POST /examples/complex-request-body 覆盖 JSON / YAML 请求体、多示例、JSON / text 响应和错误响应：

<OpenApiOperation specPath="/api" path="/examples/complex-request-body" method="post" />

渲染效果：

POST

/examples/complex-request-body

复杂请求体示例

在一个接口中覆盖嵌套 JSON 示例、YAML 示例、多种响应状态以及多种响应媒体类型。

请求体

复杂示例定义，可使用 JSON 或 YAML。

请求体属性

formathtml | pdf | markdown, 必填
枚举字段，用于展示可选输出格式。
enum: html, pdf, markdown
scopesite | published | selected, 必填
枚举字段，用于控制导出整站、已发布子集或选中页面。
enum: site, published, selected
includeDraftsboolean
带默认值的布尔字段。
default: false
callbackUrlstring<uri>
可选 URI，用于展示操作回调。
- modeall | ids | query, 必填
  控制如何解析被选中的资源。
  enum: all, ids, query

响应

Name
202
Type
object
Description
导出任务已接受。
Name
400
Type
object
Description
无效的导出请求。

请求

POST/examples/complex-request-body

curl https://api.clarify.local/v1/examples/complex-request-body \
  --request POST \
  --header 'Authorization: Bearer {token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "format": "html",
  "scope": "site",
  "includeDrafts": false,
  "callbackUrl": "https://example.com/hooks/export"
}'

响应

{
  "id": "exp_123",
  "status": "queued",
  "downloadUrl": null
}

嵌入完整 Reference

如果你希望在 MDX 页面中先写业务背景，再展示完整 API Reference，可以使用 OpenApiDocument：

# API Reference

下面是当前服务的完整接口列表。

<OpenApiDocument specPath="/api" />

这适合用于：

在 Reference 前补充认证、限流、错误格式说明。
在产品页中组合“说明 + 完整接口”。
临时把完整 Reference 放入某个专题文档中。

常见错误排查

`OpenAPI spec not found`

检查：

OpenAPI 文件是否位于 source 或当前语言目录下。
文件名是否为 .openapi.json / .openapi.yaml / .openapi.yml。
specPath 是否写的是路由，例如 /api，而不是文件名 api.openapi.json。

`Endpoint not found`

检查：

path 是否与 OpenAPI paths 键完全一致。
路径参数是否使用 {pageId} 这种 OpenAPI 写法，而不是 :pageId。
method 是否存在，并且大小写与组件约定一致。

页面构建失败

生产构建会解析并 dereference OpenAPI 规范。若规范无效，构建会失败。建议先确认 JSON / YAML 语法正确，再检查 $ref 是否能解析。