/**
 * doc-endpoints.ts — 文档端点统一注册入口
 *
 * 统一管理两个文档端点的注册：
 *   - GET /openapi.json      → 返回 OpenAPI JSON spec
 *   - GET /docs              → 返回 Scalar API Reference HTML 页面
 *                              （文档阅读 + 内置 Try it out 交互式测试）
 *   - GET /_vext/scalar.js   → 本地 Scalar JS 资产（由 registerScalarAssets 注册）
 *
 * 替代原有的 Redoc + Swagger UI 双端点方案，
 * 使用 Scalar API Reference 在单一页面同时提供文档阅读和交互式测试。
 *
 * Scalar JS 加载策略（v0.2.2 新增）：
 *   1. 用户配置了 scalar.cdnUrl → 使用用户配置（不做任何检测或安装）
 *   2. 本地已安装 @scalar/api-reference → 自动切换本地路由加载
 *   3. 本地未安装 → 自动安装后切换本地路由加载
 *   4. 安装失败 → throw 明确错误（不静默降级回 CDN）
 *
 * @module lib/openapi/doc-endpoints
 * @see 14-openapi.md §7（文档 UI 集成）
 * @changelog
 *   - v0.2.0: 从 Redoc + Swagger UI 双端点切换为 Scalar 单端点
 *             移除 ui: 'both' | 'redoc' | 'swagger' 配置
 *             简化为 /docs (Scalar) + /openapi.json (spec)
 *   - v0.2.2: 新增本地资产自动检测与安装（registerScalarAssets）
 *             彻底移除默认 CDN 依赖，解决中国大陆/内网/离线环境白屏问题
 */
import type { VextApp } from "../../types/app.js";
import type { DocEndpointsConfig } from "./types.js";
export type OpenAPISpecProvider = object | (() => object | Promise<object>);
/**
 * 注册文档端点（统一入口）
 *
 * 注册 Scalar API Reference 和 OpenAPI spec 端点。
 * 在 bootstrap 的 OpenAPI 初始化阶段调用（router-loader 之后、lockUse 之前）。
 *
 * @param app    VextApp 实例（用于访问 adapter 和 logger）
 * @param spec   OpenAPI 文档对象（由 OpenAPIGenerator.generate() 生成）
 * @param config 端点配置
 *
 * @example
 * ```typescript
 * const spec = generator.generate(collector.getRoutes())
 * registerDocEndpoints(app, spec, {
 *   specPath: '/openapi.json',
 *   docsPath: '/docs',
 *   title: 'My API',
 *   scalar: {
 *     theme: 'purple',
 *     darkMode: true,
 *   },
 * })
 * ```
 */
export declare function registerDocEndpoints(app: VextApp, spec: OpenAPISpecProvider, config: DocEndpointsConfig): void;