import type { Contract } from "../contract/contract.ts";
import type { OpenApiParameter, OpenApiOperation, OperationTransformContext, ParameterTransformContext, SchemaConverter } from "./operation.ts";
export type OpenApiPathItem = Partial<Record<"get" | "post" | "put" | "delete" | "patch", OpenApiOperation>>;
/**
 * The OpenAPI document shape returned by `createOpenApiDocument()`.
 *
 * @see {@link https://rest-rpc.dev/docs/openapi}
 */
export type OpenApiDocument = {
    /** OpenAPI specification version for the generated document. */
    openapi: string;
    /** Human-readable API metadata. */
    info: {
        /** API title shown by OpenAPI tooling. */
        title: string;
        /** API version shown by OpenAPI tooling. */
        version: string;
        /** Optional longer API description. */
        description?: string;
    };
    /** Server URLs where the API is available. */
    servers?: Array<{
        url: string;
        description?: string;
    }>;
    /** Generated OpenAPI paths keyed by path template. */
    paths: Record<string, OpenApiPathItem>;
    /** Reusable OpenAPI components such as security schemes. */
    components?: Record<string, unknown>;
    /** Tags available for grouping generated operations. */
    tags?: Array<{
        name: string;
        description?: string;
    }>;
    /** OpenAPI extension fields. */
    [key: `x-${string}`]: unknown;
};
/**
 * Options for generating an OpenAPI document from a contract.
 *
 * @remarks Without a `schemaConverter`, or when it returns `undefined`, a
 * declared schema becomes an empty OpenAPI Schema Object. Transform hooks can
 * adjust generated parameters and operations for project-specific conventions.
 *
 * @see {@link https://rest-rpc.dev/docs/openapi}
 */
export type CreateOpenApiDocumentOptions = {
    /** OpenAPI specification version to emit. */
    openapi?: string;
    /** Human-readable API metadata for the document. */
    info: OpenApiDocument["info"];
    /** Server URLs where the API is available. */
    servers?: OpenApiDocument["servers"];
    /** Reusable OpenAPI components such as security schemes. */
    components?: OpenApiDocument["components"];
    /** Tags available for grouping generated operations. */
    tags?: OpenApiDocument["tags"];
    /** Converts Standard Schema declarations into OpenAPI Schema Objects. */
    schemaConverter?: SchemaConverter;
    /** Allows project-specific changes to generated parameter objects. */
    transformParameter?: (context: ParameterTransformContext) => OpenApiParameter;
    /** Allows project-specific changes to each generated operation. */
    transformOperation?: (context: OperationTransformContext) => OpenApiOperation;
};
/**
 * Generates an OpenAPI document object from HTTP routes in a contract.
 *
 * @see {@link https://rest-rpc.dev/docs/openapi}
 */
export declare function createOpenApiDocument(contract: Contract, options: CreateOpenApiDocumentOptions): OpenApiDocument;