.opencode/node_modules/effect/dist/unstable/httpapi/OpenApi.d.ts

import type { NonEmptyArray } from "../../Array.ts";
import * as Context from "../../Context.ts";
import * as JsonSchema from "../../JsonSchema.ts";
import * as HttpApi from "./HttpApi.ts";
import type * as HttpApiGroup from "./HttpApiGroup.ts";
declare const Identifier_base: Context.ServiceClass<Identifier, "effect/httpapi/OpenApi/Identifier", string>;
/**
 * OpenAPI annotation for overriding generated identifiers, including operation ids.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Identifier extends Identifier_base {
}
declare const Title_base: Context.ServiceClass<Title, "effect/httpapi/OpenApi/Title", string>;
/**
 * OpenAPI annotation for setting the API title or group tag name.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Title extends Title_base {
}
declare const Version_base: Context.ServiceClass<Version, "effect/httpapi/OpenApi/Version", string>;
/**
 * OpenAPI annotation for setting the generated API version.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Version extends Version_base {
}
declare const Description_base: Context.ServiceClass<Description, "effect/httpapi/OpenApi/Description", string>;
/**
 * OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Description extends Description_base {
}
declare const License_base: Context.ServiceClass<License, "effect/httpapi/OpenApi/License", OpenAPISpecLicense>;
/**
 * OpenAPI annotation for setting the generated API license metadata.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class License extends License_base {
}
declare const ExternalDocs_base: Context.ServiceClass<ExternalDocs, "effect/httpapi/OpenApi/ExternalDocs", OpenAPISpecExternalDocs>;
/**
 * OpenAPI annotation for adding external documentation metadata to groups or endpoints.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class ExternalDocs extends ExternalDocs_base {
}
declare const Servers_base: Context.ServiceClass<Servers, "effect/httpapi/OpenApi/Servers", readonly OpenAPISpecServer[]>;
/**
 * OpenAPI annotation for setting the generated API server list.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Servers extends Servers_base {
}
declare const Format_base: Context.ServiceClass<Format, "effect/httpapi/OpenApi/Format", string>;
/**
 * OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Format extends Format_base {
}
declare const Summary_base: Context.ServiceClass<Summary, "effect/httpapi/OpenApi/Summary", string>;
/**
 * OpenAPI annotation for setting generated summary text.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Summary extends Summary_base {
}
declare const Deprecated_base: Context.ServiceClass<Deprecated, "effect/httpapi/OpenApi/Deprecated", boolean>;
/**
 * OpenAPI annotation for marking a generated endpoint operation as deprecated.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Deprecated extends Deprecated_base {
}
declare const Override_base: Context.ServiceClass<Override, "effect/httpapi/OpenApi/Override", Record<string, unknown>>;
/**
 * OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Override extends Override_base {
}
/**
 * Annotation that excludes an annotated group or endpoint from the generated
 * OpenAPI specification.
 *
 * **When to use**
 *
 * Use to hide internal, experimental, or otherwise undocumented HTTP API groups
 * and endpoints from generated OpenAPI output.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare const Exclude: Context.Reference<boolean>;
declare const Transform_base: Context.ServiceClass<Transform, "effect/httpapi/OpenApi/Transform", (openApiSpec: Record<string, any>) => Record<string, any>>;
/**
 * OpenAPI annotation for transforming a generated OpenAPI object.
 *
 * **Details**
 *
 * The function is applied during generation to the annotated API, group tag, or
 * endpoint operation.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare class Transform extends Transform_base {
}
/**
 * Builds a `Context` containing OpenAPI annotations from the supplied options.
 *
 * @category annotations
 * @since 4.0.0
 */
export declare const annotations: (options: {
    readonly identifier?: string | undefined;
    readonly title?: string | undefined;
    readonly version?: string | undefined;
    readonly description?: string | undefined;
    readonly license?: OpenAPISpecLicense | undefined;
    readonly summary?: string | undefined;
    readonly deprecated?: boolean | undefined;
    readonly externalDocs?: OpenAPISpecExternalDocs | undefined;
    readonly servers?: ReadonlyArray<OpenAPISpecServer> | undefined;
    readonly format?: string | undefined;
    readonly override?: Record<string, unknown> | undefined;
    readonly exclude?: boolean | undefined;
    readonly transform?: ((openApiSpec: Record<string, any>) => Record<string, any>) | undefined;
}) => Context.Context<never>;
/**
 * Converts an `HttpApi` instance into an OpenAPI Specification object.
 *
 * **Details**
 *
 * This function takes an `HttpApi` instance, which defines a structured API,
 * and generates an OpenAPI Specification (`OpenAPISpec`). The resulting spec
 * adheres to the OpenAPI 3.1.0 standard and includes detailed metadata such as
 * paths, operations, security schemes, and components. The function processes
 * the API's annotations, middleware, groups, and endpoints to build a complete
 * and accurate representation of the API in OpenAPI format.
 *
 * The function also deduplicates schemas, applies transformations, and
 * integrates annotations like descriptions, summaries, external documentation,
 * and overrides. Cached results are used for better performance when the same
 * `HttpApi` instance is processed multiple times.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(api: HttpApi.HttpApi<Id, Groups>): OpenAPISpec;
/**
 * This model describes the OpenAPI specification (version 3.1.0) returned by
 * {@link fromApi}. It is not intended to describe the entire OpenAPI
 * specification, only the output of `fromApi`.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpec {
    openapi: "3.1.0";
    info: OpenAPISpecInfo;
    paths: OpenAPISpecPaths;
    components: OpenAPIComponents;
    security: Array<OpenAPISecurityRequirement>;
    tags: Array<OpenAPISpecTag>;
    servers?: Array<OpenAPISpecServer>;
}
/**
 * OpenAPI `info` object generated by `fromApi`.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecInfo {
    title: string;
    version: string;
    description?: string;
    license?: OpenAPISpecLicense;
    summary?: string;
}
/**
 * OpenAPI tag object generated for an HTTP API group.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecTag {
    name: string;
    description?: string;
    externalDocs?: OpenAPISpecExternalDocs;
}
/**
 * OpenAPI external documentation metadata.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecExternalDocs {
    url: string;
    description?: string;
}
/**
 * OpenAPI license metadata used in the generated `info` object.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecLicense {
    name: string;
    url?: string;
    [key: string]: unknown;
}
/**
 * OpenAPI server object used in the generated `servers` array.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecServer {
    url: string;
    description?: string;
    variables?: Record<string, OpenAPISpecServerVariable>;
}
/**
 * OpenAPI variable definition for templated server URLs.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecServerVariable {
    default: string;
    enum?: NonEmptyArray<string>;
    description?: string;
}
/**
 * Generated OpenAPI `paths` object, keyed by route path.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>;
/**
 * Lowercase HTTP method names used as keys in generated OpenAPI path items.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISpecMethodName = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
/**
 * Generated OpenAPI path item mapping HTTP methods to operations for a single route path.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISpecPathItem = {
    [K in OpenAPISpecMethodName]?: OpenAPISpecOperation;
};
/**
 * Generated OpenAPI parameter object for path, query, header, or cookie parameters.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecParameter {
    name: string;
    in: "query" | "header" | "path" | "cookie";
    schema: object;
    required: boolean;
    description?: string;
}
/**
 * Generated OpenAPI responses object, keyed by HTTP status code.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>;
/**
 * Generated OpenAPI content object, keyed by media type.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenApiSpecContent = {
    [K in string]: OpenApiSpecMediaType;
};
/**
 * Generated OpenAPI response object for an endpoint success or error schema.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenApiSpecResponse {
    description: string;
    content?: OpenApiSpecContent;
}
/**
 * Generated OpenAPI media type object containing the JSON Schema for a request or response body.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenApiSpecMediaType {
    schema: JsonSchema.JsonSchema;
    "x-effect-stream"?: OpenApiSpecEffectStream;
}
/**
 * Effect-specific metadata for generated streaming response media types.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenApiSpecEffectStream = {
    encoding: "sse";
    causeSchema: JsonSchema.JsonSchema;
    errorSchema: JsonSchema.JsonSchema;
    failureEvent: "effect/httpapi/stream/failure";
} | {
    encoding: "uint8array";
};
/**
 * Generated OpenAPI request body object for endpoint payloads.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecRequestBody {
    content: OpenApiSpecContent;
    required: true;
}
/**
 * Generated OpenAPI components containing shared schemas and security schemes.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPIComponents {
    schemas: JsonSchema.Definitions;
    securitySchemes: Record<string, OpenAPISecurityScheme>;
}
/**
 * Generated OpenAPI HTTP security scheme, such as bearer or basic authentication.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPIHTTPSecurityScheme {
    readonly type: "http";
    scheme: "bearer" | "basic" | string;
    description?: string;
    bearerFormat?: string;
}
/**
 * Generated OpenAPI API key security scheme.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPIApiKeySecurityScheme {
    readonly type: "apiKey";
    name: string;
    in: "query" | "header" | "cookie";
    description?: string;
}
/**
 * Union of security scheme objects emitted in generated OpenAPI components.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme;
/**
 * Generated OpenAPI security requirement, keyed by security scheme name.
 *
 * @category models
 * @since 4.0.0
 */
export type OpenAPISecurityRequirement = Record<string, Array<string>>;
/**
 * Generated OpenAPI operation object for an HTTP API endpoint.
 *
 * @category models
 * @since 4.0.0
 */
export interface OpenAPISpecOperation {
    operationId: string;
    parameters: Array<OpenAPISpecParameter>;
    responses: OpenAPISpecResponses;
    /** Always contains at least the title annotation or the group identifier */
    tags: NonEmptyArray<string>;
    security: Array<OpenAPISecurityRequirement>;
    requestBody?: OpenAPISpecRequestBody;
    description?: string;
    summary?: string;
    deprecated?: boolean;
    externalDocs?: OpenAPISpecExternalDocs;
}
export {};
//# sourceMappingURL=OpenApi.d.ts.map