OpenAPI 参考

Clarify Complete OpenAPI Example

这是一个精简但覆盖面完整的 OpenAPI 示例：在控制接口数量的同时，用于展示 Clarify 对完整 Reference 页、标签、服务器变量、路径/查询/Header 参数、JSON 与 YAML 请求体、多种响应媒体类型、示例、链接、回调、Webhooks、安全方案、Schema 组合、可空字段、Discriminator 以及常见 JSON Schema 校验关键字的渲染支持。

版本 1.0.0

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/basic-request

多种请求体结构

演示 JSON、YAML、multipart form data、OAuth 安全配置以及回调渲染。

请求头

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

请求体

示例负载。

请求体属性

titlestring, 必填
创建页面时的标题字段；Clarify 会展示简单请求字符串和必填标记。
slugstring, 必填
创建页面时的 slug 字段，用于在示例中展示类似 pattern 的标识符。
contentstring, 必填
作者提交的 MDX 或 Markdown 源内容。
statusdraft | published | archived
Clarify 会将字符串枚举渲染为受限取值，并在 Schema 表格中展示所有可选枚举值。
enum: draft, published, archived
frontmatterobject
创建请求接受的自由结构 frontmatter 对象。
additionalProperties: true

响应

Name
201
Type
object & object
Description
页面已创建。
Name
202
Type
object
Description
使用 multipart/form-data 时，资源上传请求已被接受。
Name
400
Type
object
Description
请求无效。
Name
409
Type
object
Description
Slug 已存在。
Name
default
Type
object
Description
未知错误。

请求

POST/examples/basic-request

curl https://api.clarify.local/v1/examples/basic-request \
  --request POST \
  --header 'Authorization: Bearer {token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Getting Started",
  "slug": "getting-started",
  "content": "# Getting Started\n\nInstall Clarify.",
  "status": "draft",
  "frontmatter": {
    "description": "几分钟内安装 Clarify"
  }
}'

响应

application/json

{}

GET

/examples/path-parameters/{pageId}

路径参数示例

演示模板路径参数以及引用式响应 Schema。

路径参数

Name
pageId
Type
string, 必填
Description
页面标识符。

响应

Name
200
Type
object & object
Description
示例资源详情。
Name
404
Type
object
Description
资源不存在。
Name
default
Type
object
Description
未知错误。

请求

GET/examples/path-parameters/{pageId}

curl https://api.clarify.local/v1/examples/path-parameters/{pageId} \
  --header 'Authorization: Bearer {token}' \
  --header 'Accept: application/json'

响应

application/json

{
  "id": "pg_123",
  "title": "Getting Started",
  "slug": "getting-started",
  "status": "published",
  "content": "# Getting Started\n\nInstall Clarify.",
  "frontmatter": {
    "description": "几分钟内安装 Clarify"
  },
  "parentId": null,
  "createdAt": "2026-06-17T12:00:00Z",
  "updatedAt": "2026-06-17T12:00:00Z",
  "links": [
    {
      "href": "/getting-started",
      "label": "View page"
    }
  ]
}

GET

/examples/query-parameters

查询参数示例

覆盖必填查询参数、以 JSON 编码的查询内容、数组响应以及 CSV 替代媒体类型。

查询参数

Name
q
Type
string, 必填
Description
操作参数。
Name
filters
Description
操作参数。

请求头

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

响应

Name
200
Type
object[]
Description
搜索结果。

请求

GET/examples/query-parameters

curl 'https://search.clarify.local/us/v1/examples/query-parameters?q={q}&filters={filters}&api_key={api_key}' \
  --header 'Accept: application/json'

响应

200

[
  {
    "id": "string",
    "title": "string",
    "score": 42,
    "highlight": "string"
  }
]

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
}

GET

/examples/basic-response

基础的响应结构

一个小型公开接口，用于展示操作级安全覆盖、内联对象 Schema 和 const 值。

响应

Name
200
Type
object
Description
服务健康。

请求

GET/examples/basic-response

curl https://api.clarify.local/v1/examples/basic-response \
  --header 'Accept: application/json'

响应

200application/json

{
  "status": "string",
  "time": "string"
}