@beignet/core/dist/openapi/index.d.ts

Core framework primitives for Beignet

/**
 * @beignet/core/openapi
 *
 * OpenAPI 3.1 generation from Beignet contracts
 */
import { type ContractDeprecationMeta, type ContractLike } from "../contracts/index.js";
import { type SchemaConverter, type SchemaIntrospector } from "./schema-introspector.js";
export { createZodIntrospector, createZodSchemaConverter, type SchemaConverter, type SchemaIntrospector, } from "./schema-introspector.js";
/**
 * OpenAPI 3.1 info object.
 */
export interface OpenAPIInfo {
    /**
     * API title.
     */
    title: string;
    /**
     * API version.
     */
    version: string;
    /**
     * API description.
     */
    description?: string;
    /**
     * Terms of service URL.
     */
    termsOfService?: string;
    /**
     * API contact information.
     */
    contact?: {
        name?: string;
        url?: string;
        email?: string;
    };
    /**
     * API license information.
     */
    license?: {
        name: string;
        url?: string;
    };
}
/**
 * OpenAPI 3.1 server object.
 */
export interface OpenAPIServer {
    /**
     * Server URL.
     */
    url: string;
    /**
     * Server description.
     */
    description?: string;
    /**
     * Server URL variables.
     */
    variables?: Record<string, {
        default: string;
        enum?: string[];
        description?: string;
    }>;
}
/**
 * OpenAPI 3.1 security scheme object.
 */
export type OpenAPISecurityScheme = {
    type: "apiKey";
    name: string;
    in: "query" | "header" | "cookie";
    description?: string;
} | {
    type: "http";
    scheme: string;
    bearerFormat?: string;
    description?: string;
} | {
    type: "oauth2";
    flows: Record<string, unknown>;
    description?: string;
} | {
    type: "openIdConnect";
    openIdConnectUrl: string;
    description?: string;
};
/**
 * OpenAPI schema object.
 */
export type SchemaObject = Record<string, unknown>;
/**
 * OpenAPI reference object.
 */
export type ReferenceObject = {
    $ref: string;
};
/**
 * OpenAPI parameter object.
 */
export interface ParameterObject {
    /**
     * Parameter name.
     */
    name: string;
    /**
     * Parameter location.
     */
    in: "path" | "query" | "header" | "cookie";
    /**
     * Whether the parameter is required.
     */
    required?: boolean;
    /**
     * Parameter schema.
     */
    schema?: SchemaObject | ReferenceObject;
    /**
     * Parameter description.
     */
    description?: string;
    /**
     * Whether the parameter is deprecated.
     */
    deprecated?: boolean;
}
/**
 * OpenAPI request body object.
 */
export interface RequestBodyObject {
    /**
     * Whether the request body is required.
     */
    required?: boolean;
    /**
     * Request body description.
     */
    description?: string;
    /**
     * Request body content keyed by media type.
     */
    content: Record<string, {
        schema?: SchemaObject | ReferenceObject;
    }>;
}
/**
 * OpenAPI response object.
 */
export interface ResponseObject {
    /**
     * Response description.
     */
    description: string;
    /**
     * Response content keyed by media type.
     */
    content?: Record<string, {
        schema?: SchemaObject | ReferenceObject;
        examples?: Record<string, {
            summary?: string;
            value?: unknown;
        }>;
    }>;
}
/**
 * OpenAPI operation object.
 */
export interface OperationObject {
    /**
     * Operation ID.
     */
    operationId?: string;
    /**
     * Operation summary.
     */
    summary?: string;
    /**
     * Operation description.
     */
    description?: string;
    /**
     * Operation tags.
     */
    tags?: string[];
    /**
     * Whether the operation is deprecated.
     */
    deprecated?: boolean;
    /** Beignet lifecycle details for a deprecated operation. */
    "x-beignet-deprecation"?: ContractDeprecationMeta;
    /**
     * External documentation.
     */
    externalDocs?: {
        description?: string;
        url: string;
    };
    /**
     * Operation-specific security requirements.
     */
    security?: Array<Record<string, string[]>>;
    /**
     * Operation parameters.
     */
    parameters?: ParameterObject[];
    /**
     * Operation request body.
     */
    requestBody?: RequestBodyObject;
    /**
     * Operation responses keyed by status code.
     */
    responses: Record<string, ResponseObject>;
}
/**
 * OpenAPI path item object.
 */
export interface PathItemObject {
    get?: OperationObject;
    post?: OperationObject;
    put?: OperationObject;
    patch?: OperationObject;
    delete?: OperationObject;
    head?: OperationObject;
    options?: OperationObject;
}
/**
 * OpenAPI paths object.
 */
export type PathsObject = Record<string, PathItemObject>;
/**
 * OpenAPI components object.
 */
export interface ComponentsObject {
    /**
     * Reusable schemas keyed by component name.
     */
    schemas?: Record<string, SchemaObject>;
    /**
     * Reusable security schemes keyed by scheme name.
     */
    securitySchemes?: Record<string, OpenAPISecurityScheme>;
}
/**
 * OpenAPI 3.1 document.
 */
export interface OpenAPIObject {
    /**
     * OpenAPI version.
     */
    openapi: "3.1.0";
    /**
     * API info.
     */
    info: OpenAPIInfo;
    /**
     * Server list.
     */
    servers?: OpenAPIServer[];
    /**
     * API paths.
     */
    paths: PathsObject;
    /**
     * Reusable components.
     */
    components?: ComponentsObject;
    /**
     * Global security requirements.
     */
    security?: Array<Record<string, string[]>>;
}
/**
 * Options for generating an OpenAPI document.
 */
export interface OpenAPIGeneratorOptions {
    /** API title */
    title: string;
    /** API version */
    version: string;
    /** API description */
    description?: string;
    /** Server configurations */
    servers?: OpenAPIServer[];
    /** Media type for JSON content (default: application/json) */
    jsonMediaType?: string;
    /** Security schemes for authentication */
    securitySchemes?: Record<string, OpenAPISecurityScheme>;
    /** Global security requirements */
    security?: Array<Record<string, string[]>>;
    /**
     * Schema introspector for reading metadata from schema objects.
     * Defaults to a Zod introspector. Provide a custom implementation
     * to support other schema libraries.
     */
    schemaIntrospector?: SchemaIntrospector;
    /**
     * Schema converters used to turn contract schemas into OpenAPI schemas.
     * Custom converters run before Beignet's default Zod converter.
     */
    schemaConverters?: readonly SchemaConverter[];
}
/**
 * Contract input accepted by the OpenAPI generator.
 */
export type ContractInput = ContractLike;
/**
 * Convert contracts to an OpenAPI 3.1 document.
 *
 * @param contracts - Array of HTTP contracts (ContractBuilder instances or configs)
 * @param options - OpenAPI generation options
 * @returns OpenAPI 3.1 document object
 *
 * @example
 * ```ts
 * import { contractsToOpenAPI } from "@beignet/core/openapi";
 * import { getTodo, listTodos } from "./contracts";
 *
 * const spec = contractsToOpenAPI(
 *   [getTodo, listTodos],
 *   {
 *     title: "Todo API",
 *     version: "1.0.0",
 *     servers: [{ url: "https://api.example.com" }],
 *   }
 * );
 * ```
 */
export declare function contractsToOpenAPI(contracts: readonly ContractInput[], options: OpenAPIGeneratorOptions): OpenAPIObject;
//# sourceMappingURL=index.d.ts.map