import { type IdentityPlugin } from "@nifrajs/core/server";
/** A registered route as seen by {@link buildOpenApiDocument} - structurally a `@nifrajs/core`
 * `RouteDescriptor` (so `app.routes()` is passed straight through). */
export interface RouteLike {
    readonly method: string;
    readonly path: string;
    readonly schema?: {
        readonly body?: unknown;
        readonly query?: unknown;
        readonly response?: unknown;
    } | undefined;
}
export interface OpenApiInfo {
    readonly title?: string;
    readonly version?: string;
    readonly description?: string;
}
export interface OpenApiServer {
    readonly url: string;
    readonly description?: string;
}
export interface OpenApiTag {
    readonly name: string;
    readonly description?: string;
}
/** A security requirement: scheme name → required scopes (`[]` = no scopes). */
export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
/** Scalar API-reference UI options. */
export interface OpenApiUiOptions {
    /** Where to serve the UI page. Default `"/reference"`. */
    readonly path?: string;
    /** Page title. Defaults to `info.title`. */
    readonly title?: string;
    /** The Scalar script URL (loaded from a CDN). Default jsDelivr's `@scalar/api-reference`. */
    readonly cdn?: string;
}
export interface OpenApiOptions {
    readonly info?: OpenApiInfo;
    readonly servers?: readonly OpenApiServer[];
    /** Tag definitions (top-level `tags`). Reference them from an operation via `operations`. */
    readonly tags?: readonly OpenApiTag[];
    /** Reusable security schemes → `components.securitySchemes` (e.g. `{ bearer: { type: "http", scheme: "bearer" } }`). */
    readonly securitySchemes?: Readonly<Record<string, Record<string, unknown>>>;
    /** Document-wide security requirement; override per-operation via `operations`. */
    readonly security?: readonly SecurityRequirement[];
    /** Where the plugin serves the document. Default `"/openapi.json"`. */
    readonly path?: string;
    /** Exclude routes from the document (the doc path itself is always excluded). */
    readonly exclude?: (route: {
        readonly method: string;
        readonly path: string;
    }) => boolean;
    /** Per-operation overrides keyed by `"GET /users/:id"`, shallow-merged over the generated skeleton -
     * the escape hatch for rich request/response schemas, tags, and per-op security (Standard Schema
     * can't be introspected). */
    readonly operations?: Readonly<Record<string, Record<string, unknown>>>;
    /** Also serve a Scalar API-reference UI page rendering the spec (`true` → `/reference`). */
    readonly ui?: boolean | OpenApiUiOptions;
}
/**
 * Build an OpenAPI 3.1 document from a route list. Delegates to `@nifrajs/schema`'s `toOpenAPI`, so a
 * route validated with `t` (TypeBox) emits full field-level request/query/response schemas plus
 * `$ref`-reused `components.schemas`; a BYO Standard Schema (zod/valibot/arktype) exposes no portable
 * JSON-Schema form, so its body/response is omitted (supply it via `options.operations`). Path params,
 * wildcards, tags, security, and servers always emit. Exported so you can also generate the doc at
 * build time (write it to disk in CI) without booting the server.
 */
export declare function buildOpenApiDocument(routes: readonly RouteLike[], options?: OpenApiOptions): Record<string, unknown>;
/**
 * Serve an OpenAPI 3.1 document (a structural subset - see {@link buildOpenApiDocument}) at
 * `options.path` (default `/openapi.json`), generated from the app's registered routes. Generation is
 * **lazy + memoized**: it reads `app.routes()` on the first request, by which point every route is
 * registered - so the plugin's own position in the chain doesn't matter.
 *
 * Pass `ui: true` (or `ui: { path, title, cdn }`) to also serve a Scalar API-reference page (default
 * `/reference`) that renders the spec. The page loads Scalar from a CDN; pin/self-host via `ui.cdn`,
 * and remember to allow that origin if you ship a `script-src` Content-Security-Policy.
 *
 * ```ts
 * app.use(openapi({ info: { title: "My API", version: "1.0.0" }, ui: true }))
 * ```
 */
export declare function openapi(options?: OpenApiOptions): IdentityPlugin;
//# sourceMappingURL=openapi.d.ts.map