API 文档示例

本页展示 Clarify 如何把同一份 OpenAPI 规范用于完整 Reference 和 MDX 接口嵌入。

示例规范位于 source/zh-CN/api.openapi.json，生成的完整页面是 API Reference。

示例规范覆盖范围

当前示例是一个 OpenAPI 3.1 fixture，用来覆盖常见渲染场景：

info、servers、externalDocs、tags
全局 security 和 components.securitySchemes
path / query / header 参数
JSON、YAML、multipart、merge-patch 等请求体
多状态码响应、headers、examples、links
allOf、oneOf、enum、const、format、pattern、additionalProperties、discriminator
callbacks、webhooks、OpenAPI 3.1 jsonSchemaDialect

接口目录预览

GET     /examples/basic-request                 Basic request structure
POST    /examples/basic-request                 Request body variants
GET     /examples/path-parameters/{pageId}      Path parameter example
GET     /examples/query-parameters              Query parameter example
POST    /examples/complex-request-body          Complex request body example
GET     /examples/basic-response                Basic response structure

示例一：基础请求结构

在指南中解释基础请求结构时，可以直接嵌入 GET /examples/basic-request：

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

渲染效果：

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
  }
}

示例二：复杂请求体和多响应

POST /examples/complex-request-body 覆盖更复杂的接口结构：请求体有 JSON 与 YAML 两种 media type，每种 media type 下都有多个 examples；响应包含 202 和 400，成功响应同时提供 JSON 与纯文本 media type。

<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
}

原始规范

构建后，原始 OpenAPI 文件会输出到稳定 URL：

api.openapi.json

这个链接也会出现在 llms.txt 中，方便 AI 工具读取机器可解析的接口规范。