{
  "openapi": "3.1.0",
  "info": {
    "title": "Clarify Complete OpenAPI Example",
    "summary": "用于覆盖渲染能力的完整 OpenAPI 示例。",
    "description": "这是一个精简但覆盖面完整的 OpenAPI 示例：在控制接口数量的同时，用于展示 Clarify 对完整 Reference 页、标签、服务器变量、路径/查询/Header 参数、JSON 与 YAML 请求体、多种响应媒体类型、示例、链接、回调、Webhooks、安全方案、Schema 组合、可空字段、Discriminator 以及常见 JSON Schema 校验关键字的渲染支持。",
    "termsOfService": "https://clarify.local/terms",
    "contact": {
      "name": "Clarify Maintainers",
      "url": "https://github.com/taicode-labs/clarify",
      "email": "maintainers@clarify.local"
    },
    "license": {
      "name": "MIT",
      "identifier": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0.0"
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://api.clarify.local/{version}",
      "description": "生产环境",
      "variables": {
        "version": {
          "default": "v1",
          "enum": [
            "v1",
            "v2"
          ],
          "description": "API 版本"
        }
      }
    },
    {
      "url": "https://staging-api.clarify.local/v1",
      "description": "预发环境"
    }
  ],
  "externalDocs": {
    "description": "Clarify 文档",
    "url": "https://clarify.local/docs"
  },
  "tags": [
    {
      "name": "Pages",
      "description": "文档页面管理",
      "externalDocs": {
        "description": "页面指南",
        "url": "https://clarify.local/docs/pages"
      }
    },
    {
      "name": "Assets",
      "description": "资源上传与元数据"
    },
    {
      "name": "Search",
      "description": "搜索索引与查询"
    },
    {
      "name": "System",
      "description": "运行状态接口"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/examples/basic-request": {
      "summary": "基础请求示例",
      "description": "演示常见请求参数和响应元数据。",
      "parameters": [
        {
          "$ref": "#/components/parameters/TraceId"
        }
      ],
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "demoBasicRequest",
        "summary": "基础的请求结构",
        "description": "演示路径级 Header、查询参数、示例、响应 Header、链接和安全配置覆盖。",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageCursor"
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "name": "status",
            "in": "query",
            "description": "按发布状态筛选。",
            "schema": {
              "$ref": "#/components/schemas/PageStatus"
            },
            "examples": {
              "published": {
                "summary": "仅发布页面",
                "value": "published"
              }
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "需要一并返回的关联资源。",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "authors",
                  "assets",
                  "children"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "页面集合。",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageList"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/PageListExample"
                  }
                }
              }
            },
            "links": {
              "GetPageById": {
                "$ref": "#/components/links/GetPageById"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Pages"
        ],
        "operationId": "demoRequestBodyVariants",
        "summary": "多种请求体结构",
        "description": "演示 JSON、YAML、multipart form data、OAuth 安全配置以及回调渲染。",
        "requestBody": {
          "required": true,
          "description": "示例负载。",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageCreate"
              },
              "examples": {
                "guide": {
                  "$ref": "#/components/examples/PageCreateExample"
                }
              }
            },
            "application/x-yaml": {
              "schema": {
                "type": "string",
                "description": "页面负载的 YAML 表示。"
              },
              "example": "title: Getting Started\nslug: getting-started\ncontent: '# Hello'\n"
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "二进制文件字段；Clarify 会以 string format=binary 的方式渲染上传字段。"
                  },
                  "metadata": {
                    "$ref": "#/components/schemas/AssetMetadata"
                  }
                }
              },
              "encoding": {
                "metadata": {
                  "contentType": "application/json"
                }
              },
              "examples": {
                "image": {
                  "summary": "图片上传",
                  "value": {
                    "metadata": {
                      "alt": "Clarify dashboard screenshot",
                      "caption": "Generated docs preview",
                      "tags": [
                        "docs",
                        "openapi"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "页面已创建。",
            "headers": {
              "Location": {
                "description": "已创建页面的 URL。",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "202": {
            "description": "使用 multipart/form-data 时，资源上传请求已被接受。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Asset"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "description": "Slug 已存在。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "callbacks": {
          "pagePublished": {
            "$ref": "#/components/callbacks/PagePublished"
          }
        },
        "security": [
          {
            "OAuth2": [
              "pages:write"
            ]
          }
        ]
      }
    },
    "/examples/path-parameters/{pageId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PageId"
        }
      ],
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "demoPathParameters",
        "summary": "路径参数示例",
        "description": "演示模板路径参数以及引用式响应 Schema。",
        "responses": {
          "200": {
            "description": "示例资源详情。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/PageExample"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        }
      }
    },
    "/examples/query-parameters": {
      "get": {
        "tags": [
          "Search"
        ],
        "operationId": "demoQueryParameters",
        "summary": "查询参数示例",
        "description": "覆盖必填查询参数、JSON 编码的查询内容、数组响应、Query API Key 鉴权，以及作为可选媒体类型的 CSV。",
        "security": [
          {
            "QueryApiKeyAuth": []
          }
        ],
        "servers": [
          {
            "url": "https://search.clarify.local/{region}/{version}",
            "description": "区域搜索服务器",
            "variables": {
              "region": {
                "default": "us",
                "enum": [
                  "us",
                  "eu",
                  "apac"
                ],
                "description": "搜索区域"
              },
              "version": {
                "default": "v1",
                "enum": [
                  "v1",
                  "v2"
                ],
                "description": "搜索 API 版本"
              }
            }
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/TraceId"
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "openapi"
          },
          {
            "name": "filters",
            "in": "query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFilters"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "搜索结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SearchResult"
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "id,title,score\npg_123,Getting Started,0.97\n"
              }
            }
          }
        },
        "deprecated": false,
        "description": "覆盖必填查询参数、以 JSON 编码的查询内容、数组响应以及 CSV 替代媒体类型。"
      }
    },
    "/examples/complex-request-body": {
      "post": {
        "tags": [
          "Pages"
        ],
        "operationId": "demoComplexRequestBody",
        "summary": "复杂请求体示例",
        "description": "在一个接口中覆盖嵌套 JSON 示例、YAML 示例、多种响应状态以及多种响应媒体类型。",
        "requestBody": {
          "required": true,
          "description": "复杂示例定义，可使用 JSON 或 YAML。",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExportRequest"
              },
              "examples": {
                "fullSite": {
                  "summary": "整站导出",
                  "value": {
                    "format": "html",
                    "scope": "site",
                    "includeDrafts": false,
                    "callbackUrl": "https://example.com/hooks/export"
                  }
                },
                "publishedPdf": {
                  "summary": "已发布内容 PDF 导出",
                  "value": {
                    "format": "pdf",
                    "scope": "published",
                    "includeDrafts": false
                  }
                },
                "selectedWithOptions": {
                  "summary": "带嵌套选项的指定页面导出",
                  "value": {
                    "format": "html",
                    "scope": "selected",
                    "includeDrafts": true,
                    "callbackUrl": "https://example.com/hooks/export",
                    "selection": {
                      "rootPageId": "pg_docs",
                      "pageIds": [
                        "pg_intro",
                        "pg_api",
                        "pg_guides"
                      ],
                      "filters": {
                        "tags": [
                          "release",
                          "public"
                        ],
                        "updatedAfter": "2026-06-01T00:00:00Z"
                      }
                    },
                    "rendering": {
                      "theme": {
                        "mode": "dark",
                        "brandColor": "#2563eb",
                        "logo": {
                          "assetId": "asset_logo",
                          "alt": "Clarify"
                        }
                      },
                      "navigation": {
                        "includeHidden": false,
                        "levels": [
                          {
                            "depth": 1,
                            "label": "Sections"
                          },
                          {
                            "depth": 2,
                            "label": "Pages"
                          }
                        ]
                      }
                    },
                    "delivery": {
                      "archive": {
                        "type": "zip",
                        "checksum": "sha256"
                      },
                      "destinations": [
                        {
                          "type": "webhook",
                          "url": "https://example.com/hooks/export-ready",
                          "headers": {
                            "X-Project": "clarify"
                          }
                        },
                        {
                          "type": "storage",
                          "bucket": "docs-exports",
                          "path": "clarify/2026-06"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "application/x-yaml": {
              "schema": {
                "type": "string",
                "description": "导出任务的 YAML 表示。"
              },
              "examples": {
                "siteYaml": {
                  "summary": "整站 YAML",
                  "value": "format: html\nscope: site\nincludeDrafts: false\ncallbackUrl: https://example.com/hooks/export\n"
                },
                "draftYaml": {
                  "summary": "草稿 YAML",
                  "value": "format: markdown\nscope: site\nincludeDrafts: true\n"
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "导出任务已接受。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportJob"
                },
                "examples": {
                  "queued": {
                    "summary": "排队中的任务",
                    "value": {
                      "id": "exp_123",
                      "status": "queued",
                      "downloadUrl": null
                    }
                  },
                  "processing": {
                    "summary": "处理中的任务",
                    "value": {
                      "id": "exp_456",
                      "status": "processing",
                      "downloadUrl": null
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "plain": {
                    "summary": "纯文本任务 ID",
                    "value": "exp_123"
                  }
                }
              }
            }
          },
          "400": {
            "description": "无效的导出请求。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "unsupportedFormat": {
                    "summary": "不支持的格式",
                    "value": {
                      "type": "https://clarify.local/problems/unsupported-export-format",
                      "title": "Unsupported export format",
                      "status": 400,
                      "detail": "The requested export format is not available."
                    }
                  },
                  "missingScope": {
                    "summary": "缺少导出范围",
                    "value": {
                      "type": "https://clarify.local/problems/missing-export-scope",
                      "title": "Missing export scope",
                      "status": 400,
                      "detail": "Select which pages should be exported."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/examples/basic-response": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "demoBasicResponse",
        "summary": "基础的响应结构",
        "security": [],
        "responses": {
          "200": {
            "description": "服务健康。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "time"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "ok"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "一个小型公开接口，用于展示操作级安全覆盖、内联对象 Schema 和 const 值。"
      }
    }
  },
  "webhooks": {
    "pageLifecycle": {
      "post": {
        "tags": [
          "Pages"
        ],
        "operationId": "pageLifecycleWebhook",
        "summary": "页面生命周期 Webhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PagePublishedEvent"
                  },
                  {
                    "$ref": "#/components/schemas/PageDeletedEvent"
                  }
                ],
                "discriminator": {
                  "propertyName": "type",
                  "mapping": {
                    "page.published": "#/components/schemas/PagePublishedEvent",
                    "page.deleted": "#/components/schemas/PageDeletedEvent"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Webhook 已接受。"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PageStatus": {
        "type": "string",
        "enum": [
          "draft",
          "published",
          "archived"
        ],
        "description": "Clarify 会将字符串枚举渲染为受限取值，并在 Schema 表格中展示所有可选枚举值。"
      },
      "Identifier": {
        "type": "string",
        "pattern": "^[a-z]{2,}_[A-Za-z0-9]+$",
        "examples": [
          "pg_123"
        ],
        "description": "Clarify 支持通过 $ref 复用基础类型 Schema，并展示正则 pattern 与 examples。"
      },
      "Timestamp": {
        "type": "string",
        "format": "date-time",
        "examples": [
          "2026-06-17T12:00:00Z"
        ],
        "description": "Clarify 会展示 date-time 等字符串 format，并为标量字段展示 examples。"
      },
      "PageBase": {
        "type": "object",
        "required": [
          "id",
          "title",
          "slug",
          "status",
          "content",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier",
            "description": "可复用的标识符引用；用于验证对象属性中的 $ref 解析。"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "examples": [
              "Getting Started"
            ],
            "description": "必填字符串字段，包含 minLength/maxLength，便于 Clarify 展示校验约束。"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "带 pattern 约束的路由片段，会作为字符串 Schema 渲染。"
          },
          "status": {
            "$ref": "#/components/schemas/PageStatus",
            "description": "引用枚举，展示 draft、published、archived 三种状态。"
          },
          "content": {
            "type": "string",
            "contentMediaType": "text/markdown",
            "description": "使用 contentMediaType 标注文档内容字符串，用于展示富文本负载。"
          },
          "frontmatter": {
            "type": "object",
            "additionalProperties": true,
            "examples": [
              {
                "title": "Getting Started",
                "description": "几分钟内安装 Clarify"
              }
            ],
            "description": "自由结构对象，用于展示 additionalProperties 与对象示例。"
          },
          "parentId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Identifier"
              },
              {
                "type": "null"
              }
            ],
            "description": "可空父级关系，使用 oneOf 和 null 表示。"
          },
          "createdAt": {
            "$ref": "#/components/schemas/Timestamp",
            "description": "引用 date-time 字符串，表示创建时间。"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/Timestamp",
            "description": "引用 date-time 字符串，表示更新时间。"
          }
        },
        "description": "Clarify 会渲染必填对象字段、嵌套元数据、可空引用以及 Markdown 内容标注。"
      },
      "Page": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PageBase"
          },
          {
            "type": "object",
            "properties": {
              "links": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "href",
                    "label"
                  ],
                  "properties": {
                    "href": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "每个相关页面链接使用 URI-reference 渲染。"
                    },
                    "label": {
                      "type": "string",
                      "description": "嵌套内联对象中的可读链接标签。"
                    }
                  }
                },
                "description": "内联对象数组，用于验证嵌套数组、必填子字段和 URI-reference 格式。"
              }
            }
          }
        ],
        "description": "Clarify 会解析 allOf 组合，让共享基础字段与扩展字段可以一起展示。"
      },
      "PageCreate": {
        "type": "object",
        "required": [
          "title",
          "slug",
          "content"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "创建页面时的标题字段；Clarify 会展示简单请求字符串和必填标记。"
          },
          "slug": {
            "type": "string",
            "description": "创建页面时的 slug 字段，用于在示例中展示类似 pattern 的标识符。"
          },
          "content": {
            "type": "string",
            "description": "作者提交的 MDX 或 Markdown 源内容。"
          },
          "status": {
            "$ref": "#/components/schemas/PageStatus",
            "description": "可选枚举字段，使用可复用 Schema 引用。"
          },
          "frontmatter": {
            "type": "object",
            "additionalProperties": true,
            "description": "创建请求接受的自由结构 frontmatter 对象。"
          }
        },
        "additionalProperties": false,
        "description": "Clarify 会展示仅用于请求的对象 Schema、必填字段、校验限制和 additionalProperties 约束。"
      },
      "PagePatch": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "可选 patch 字符串；父级 minProperties 确保至少提供一个字段。"
          },
          "content": {
            "type": "string",
            "description": "merge-patch 示例中的可选替换内容。"
          },
          "status": {
            "$ref": "#/components/schemas/PageStatus",
            "description": "局部更新负载中的可选引用枚举。"
          },
          "parentId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Identifier"
              },
              {
                "type": "null"
              }
            ],
            "description": "patch 请求中的可空关系字段。"
          }
        },
        "minProperties": 1,
        "description": "Clarify 支持带 minProperties 与可空 oneOf 字段的局部更新负载。"
      },
      "PageList": {
        "type": "object",
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Page"
            },
            "description": "引用 Page 对象的数组；用于展示 items 为 $ref Schema 的数组。"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        },
        "description": "Clarify 会渲染引用对象数组以及嵌套分页对象。"
      },
      "Pagination": {
        "type": "object",
        "required": [
          "limit",
          "hasMore"
        ],
        "properties": {
          "cursor": {
            "type": "string",
            "description": "不透明分页游标；可选字段不会显示必填标记。"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20,
            "description": "包含 minimum、maximum 和 default 的整数。"
          },
          "hasMore": {
            "type": "boolean",
            "description": "布尔标记，用于表示是否还有下一页。"
          }
        },
        "description": "Clarify 会在分页模型中展示整数范围、默认值和布尔值。"
      },
      "AssetMetadata": {
        "type": "object",
        "properties": {
          "alt": {
            "type": "string",
            "description": "上传元数据示例中的图片替代文本。"
          },
          "caption": {
            "type": "string",
            "description": "用于资源展示的可选说明文字。"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "uniqueItems": true,
            "description": "唯一字符串数组，用于验证数组约束。"
          }
        },
        "description": "Clarify 覆盖数组、uniqueItems 以及 multipart 示例中的自由结构元数据。"
      },
      "Asset": {
        "type": "object",
        "required": [
          "id",
          "url",
          "contentType",
          "size"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier",
            "description": "可复用资源标识符。"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "已上传资源的绝对 URI。"
          },
          "contentType": {
            "type": "string",
            "description": "上传后返回的 MIME 类型字符串。"
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "description": "非负整数字节大小。"
          },
          "metadata": {
            "$ref": "#/components/schemas/AssetMetadata",
            "description": "从 multipart 请求示例复用的嵌套元数据对象。"
          }
        },
        "description": "Clarify 覆盖 URI 字符串、非负整数和可复用嵌套元数据对象。"
      },
      "SearchFilters": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "编码在 JSON 查询参数中的数组筛选条件。"
          },
          "updatedAfter": {
            "type": "string",
            "format": "date-time",
            "description": "date-time 筛选条件，用于展示带 format 的查询内容。"
          }
        },
        "description": "Clarify 支持以 JSON 内容编码的对象型查询参数。"
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "id",
          "title",
          "score"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier",
            "description": "匹配页面的引用标识符。"
          },
          "title": {
            "type": "string",
            "description": "匹配页面标题。"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0 到 1 之间的数字，便于 Clarify 展示数值边界。"
          },
          "highlight": {
            "type": "string",
            "description": "搜索返回的可选高亮片段。"
          }
        },
        "description": "Clarify 会在响应数组中展示数值范围、可选字符串和引用标识符。"
      },
      "ExportRequest": {
        "type": "object",
        "required": [
          "format",
          "scope",
          "selection",
          "rendering",
          "delivery"
        ],
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "html",
              "pdf",
              "markdown"
            ],
            "description": "枚举字段，用于展示可选输出格式。"
          },
          "scope": {
            "type": "string",
            "enum": [
              "site",
              "published",
              "selected"
            ],
            "description": "枚举字段，用于控制导出整站、已发布子集或选中页面。"
          },
          "includeDrafts": {
            "type": "boolean",
            "default": false,
            "description": "带默认值的布尔字段。"
          },
          "callbackUrl": {
            "type": "string",
            "format": "uri",
            "description": "可选 URI，用于展示操作回调。"
          },
          "selection": {
            "type": "object",
            "required": [
              "mode",
              "items"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "all",
                  "ids",
                  "query"
                ],
                "description": "控制如何解析被选中的资源。"
              },
              "items": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "type"
                  ],
                  "properties": {
                    "id": {
                      "$ref": "#/components/schemas/Identifier",
                      "description": "选中资源标识符。"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "page",
                        "section",
                        "asset"
                      ],
                      "description": "选中资源类型。"
                    },
                    "options": {
                      "type": "object",
                      "additionalProperties": {
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          }
                        ]
                      },
                      "description": "每个资源的自由选项，值可以是基础类型。"
                    }
                  }
                },
                "description": "选中资源组成的嵌套数组。"
              },
              "query": {
                "$ref": "#/components/schemas/SearchFilters",
                "description": "mode 为 query 时使用的可选对象查询。"
              }
            },
            "description": "嵌套对象，用于展示必填子属性、数组、引用和 additionalProperties。"
          },
          "rendering": {
            "type": "object",
            "required": [
              "theme",
              "assets"
            ],
            "properties": {
              "theme": {
                "oneOf": [
                  {
                    "const": "system",
                    "description": "使用默认主题。"
                  },
                  {
                    "type": "object",
                    "required": [
                      "name",
                      "tokens"
                    ],
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "自定义主题名称。"
                      },
                      "tokens": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string",
                          "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
                        },
                        "description": "颜色 token 映射，限制为十六进制颜色。"
                      }
                    }
                  }
                ],
                "description": "oneOf 字段，可以是 const 字符串或内联对象。"
              },
              "assets": {
                "type": "object",
                "required": [
                  "embed",
                  "metadata"
                ],
                "properties": {
                  "embed": {
                    "type": "boolean",
                    "default": true,
                    "description": "是否内嵌资源。"
                  },
                  "metadata": {
                    "$ref": "#/components/schemas/AssetMetadata",
                    "description": "引用的嵌套元数据 schema。"
                  }
                }
              }
            },
            "description": "渲染设置，用于展示 oneOf、const、默认值、嵌套对象和引用。"
          },
          "delivery": {
            "type": "object",
            "required": [
              "channels"
            ],
            "properties": {
              "channels": {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "kind",
                        "email"
                      ],
                      "properties": {
                        "kind": {
                          "const": "email"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "kind",
                        "url"
                      ],
                      "properties": {
                        "kind": {
                          "const": "webhook"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  ]
                },
                "description": "带 const 判别字段的 oneOf 渠道对象数组。"
              },
              "expiresAt": {
                "oneOf": [
                  {
                    "type": "string",
                    "format": "date-time"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "可为空的过期时间。"
              }
            },
            "description": "投递配置，用于展示数组、oneOf 分支、格式和可空字段。"
          }
        },
        "description": "复杂嵌套导出请求，覆盖枚举、默认值、引用、数组、oneOf、const、格式、pattern 和 additionalProperties。"
      },
      "ExportJob": {
        "type": "object",
        "required": [
          "id",
          "status",
          "downloadUrl"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier",
            "description": "可复用任务标识符。"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "ready",
              "failed"
            ],
            "description": "异步任务的枚举生命周期。"
          },
          "downloadUrl": {
            "oneOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ],
            "description": "导出完成后可用的可空 URI。"
          }
        },
        "description": "Clarify 会通过 oneOf/null 渲染可空字段，并展示异步任务状态枚举。"
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "问题类型 URI-reference。"
          },
          "title": {
            "type": "string",
            "description": "简短且可读的错误标题。"
          },
          "status": {
            "type": "integer",
            "description": "用整数表示的 HTTP 状态码。"
          },
          "detail": {
            "type": "string",
            "description": "可选的详细错误说明。"
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "本次错误实例的可选 URI-reference。"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "path",
                "message"
              ],
              "properties": {
                "path": {
                  "type": "string",
                  "description": "无效字段的 JSON Pointer 或点分路径。"
                },
                "message": {
                  "type": "string",
                  "description": "与字段路径关联的校验消息。"
                }
              }
            },
            "description": "嵌套校验错误数组，并包含必填子属性。"
          }
        },
        "description": "Clarify 支持 RFC 7807 风格错误结构、嵌套校验错误数组和 URI-reference 格式。"
      },
      "EventBase": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier",
            "description": "可复用事件标识符。"
          },
          "type": {
            "type": "string",
            "description": "Discriminator 使用的事件类型字符串。"
          },
          "createdAt": {
            "$ref": "#/components/schemas/Timestamp",
            "description": "事件发出的 date-time 时间。"
          }
        },
        "description": "Clarify 会展示回调与 Webhooks 共用的事件信封结构。"
      },
      "PagePublishedEvent": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EventBase"
          },
          {
            "type": "object",
            "required": [
              "type",
              "data"
            ],
            "properties": {
              "type": {
                "const": "page.published",
                "description": "Discriminator 映射使用的 const 事件类型。"
              },
              "data": {
                "$ref": "#/components/schemas/Page",
                "description": "从引用或内联 Schema 渲染的事件负载。"
              }
            }
          }
        ],
        "description": "Clarify 展示 allOf 与 const 字段组合，以支持适合 Discriminator 的事件变体。"
      },
      "PageDeletedEvent": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EventBase"
          },
          {
            "type": "object",
            "required": [
              "type",
              "data"
            ],
            "properties": {
              "type": {
                "const": "page.deleted",
                "description": "Discriminator 映射使用的 const 事件类型。"
              },
              "data": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/Identifier"
                  }
                },
                "description": "从引用或内联 Schema 渲染的事件负载。"
              }
            }
          }
        ],
        "description": "Clarify 展示另一个 Discriminator 映射分支，并使用紧凑数据负载。"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求无效。",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "invalidCursor": {
                "summary": "游标无效",
                "value": {
                  "type": "https://clarify.local/problems/invalid-cursor",
                  "title": "Invalid cursor",
                  "status": 400,
                  "detail": "The cursor is malformed."
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "凭证缺失或无效。"
      },
      "NotFound": {
        "description": "资源不存在。",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ValidationError": {
        "description": "校验失败。",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "UnexpectedError": {
        "description": "未知错误。",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "parameters": {
      "TraceId": {
        "name": "X-Trace-Id",
        "in": "header",
        "description": "请求链路中透传的可选 Trace ID。",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "PageId": {
        "name": "pageId",
        "in": "path",
        "required": true,
        "description": "页面标识符。",
        "schema": {
          "$ref": "#/components/schemas/Identifier"
        }
      },
      "PageCursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "PageLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      }
    },
    "examples": {
      "PageExample": {
        "summary": "已发布页面",
        "value": {
          "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"
            }
          ]
        }
      },
      "PageListExample": {
        "summary": "分页页面列表",
        "value": {
          "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
          }
        }
      },
      "PageCreateExample": {
        "summary": "创建指南页面",
        "value": {
          "title": "Getting Started",
          "slug": "getting-started",
          "content": "# Getting Started\n\nInstall Clarify.",
          "status": "draft",
          "frontmatter": {
            "description": "几分钟内安装 Clarify"
          }
        }
      }
    },
    "requestBodies": {
      "PageUpsert": {
        "required": true,
        "description": "完整页面替换负载。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PageCreate"
            }
          }
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "请求标识符。",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitRemaining": {
        "description": "当前窗口内剩余请求数。",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "QueryApiKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      },
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.clarify.local/oauth/authorize",
            "tokenUrl": "https://auth.clarify.local/oauth/token",
            "scopes": {
              "pages:read": "Read pages",
              "pages:write": "Create and update pages"
            }
          }
        }
      },
      "OpenIdConnect": {
        "type": "openIdConnect",
        "openIdConnectUrl": "https://auth.clarify.local/.well-known/openid-configuration"
      }
    },
    "links": {
      "GetPageById": {
        "operationId": "demoPathParameters",
        "parameters": {
          "pageId": "$response.body#/data/0/id"
        },
        "description": "使用返回结果中的第一个 ID 跳转到路径参数示例。"
      }
    },
    "callbacks": {
      "PagePublished": {
        "{$request.body#/callbackUrl}": {
          "post": {
            "requestBody": {
              "required": true,
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PagePublishedEvent"
                  }
                }
              }
            },
            "responses": {
              "204": {
                "description": "回调已接受。"
              }
            }
          }
        }
      }
    },
    "pathItems": {
      "Health": {
        "get": {
          "summary": "可复用健康检查",
          "responses": {
            "200": {
              "description": "正常"
            }
          }
        }
      }
    }
  }
}