hono-openapi 0.4.8 → 0.5.0-rc.0

package/dist/index.d.cts

@@ -0,0 +1,413 @@
+import * as openapi_types from 'openapi-types';
+import { OpenAPIV3_1 } from 'openapi-types';
+import { MiddlewareHandler, ValidationTargets, Env, Input, Context, Hono } from 'hono';
+import { ValidationTargets as ValidationTargets$1, RouterRoute, BlankEnv, Input as Input$1, BlankInput, Schema, BlankSchema } from 'hono/types';
+import { Hook } from '@hono/standard-validator';
+
+// ==================================================================================================
+// JSON Schema Draft 07
+// ==================================================================================================
+// https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+// --------------------------------------------------------------------------------------------------
+
+/**
+ * Primitive type
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+type JSONSchema7TypeName =
+    | "string" //
+    | "number"
+    | "integer"
+    | "boolean"
+    | "object"
+    | "array"
+    | "null";
+
+/**
+ * Primitive type
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+type JSONSchema7Type =
+    | string //
+    | number
+    | boolean
+    | JSONSchema7Object
+    | JSONSchema7Array
+    | null;
+
+// Workaround for infinite type recursion
+interface JSONSchema7Object {
+    [key: string]: JSONSchema7Type;
+}
+
+// Workaround for infinite type recursion
+// https://github.com/Microsoft/TypeScript/issues/3496#issuecomment-128553540
+interface JSONSchema7Array extends Array<JSONSchema7Type> {}
+
+/**
+ * Meta schema
+ *
+ * Recommended values:
+ * - 'http://json-schema.org/schema#'
+ * - 'http://json-schema.org/hyper-schema#'
+ * - 'http://json-schema.org/draft-07/schema#'
+ * - 'http://json-schema.org/draft-07/hyper-schema#'
+ *
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+ */
+type JSONSchema7Version = string;
+
+/**
+ * JSON Schema v7
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+ */
+type JSONSchema7Definition = JSONSchema7 | boolean;
+interface JSONSchema7 {
+    $id?: string | undefined;
+    $ref?: string | undefined;
+    $schema?: JSONSchema7Version | undefined;
+    $comment?: string | undefined;
+
+    /**
+     * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.2.4
+     * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#appendix-A
+     */
+    $defs?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
+     */
+    type?: JSONSchema7TypeName | JSONSchema7TypeName[] | undefined;
+    enum?: JSONSchema7Type[] | undefined;
+    const?: JSONSchema7Type | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
+     */
+    multipleOf?: number | undefined;
+    maximum?: number | undefined;
+    exclusiveMaximum?: number | undefined;
+    minimum?: number | undefined;
+    exclusiveMinimum?: number | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
+     */
+    maxLength?: number | undefined;
+    minLength?: number | undefined;
+    pattern?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
+     */
+    items?: JSONSchema7Definition | JSONSchema7Definition[] | undefined;
+    additionalItems?: JSONSchema7Definition | undefined;
+    maxItems?: number | undefined;
+    minItems?: number | undefined;
+    uniqueItems?: boolean | undefined;
+    contains?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
+     */
+    maxProperties?: number | undefined;
+    minProperties?: number | undefined;
+    required?: string[] | undefined;
+    properties?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+    patternProperties?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+    additionalProperties?: JSONSchema7Definition | undefined;
+    dependencies?: {
+        [key: string]: JSONSchema7Definition | string[];
+    } | undefined;
+    propertyNames?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
+     */
+    if?: JSONSchema7Definition | undefined;
+    then?: JSONSchema7Definition | undefined;
+    else?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
+     */
+    allOf?: JSONSchema7Definition[] | undefined;
+    anyOf?: JSONSchema7Definition[] | undefined;
+    oneOf?: JSONSchema7Definition[] | undefined;
+    not?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
+     */
+    format?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-8
+     */
+    contentMediaType?: string | undefined;
+    contentEncoding?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-9
+     */
+    definitions?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+     */
+    title?: string | undefined;
+    description?: string | undefined;
+    default?: JSONSchema7Type | undefined;
+    readOnly?: boolean | undefined;
+    writeOnly?: boolean | undefined;
+    examples?: JSONSchema7Type | undefined;
+}
+
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    export interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    export type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    export interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    export interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    export interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    export interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    export interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+    export {  };
+}
+
+/**
+ * Generate a resolver for a validation schema
+ * @param schema Validation schema
+ * @returns Resolver result
+ */
+declare function resolver<Schema extends StandardSchemaV1>(schema: Schema): {
+    vendor: string;
+    validate: (value: unknown) => StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;
+    toJSONSchema: (options?: Record<string, unknown>) => Promise<JSONSchema7>;
+    toOpenAPISchema: (options?: Record<string, unknown>) => Promise<{
+        schema: OpenAPIV3_1.SchemaObject;
+        components: OpenAPIV3_1.ComponentsObject | undefined;
+    }>;
+};
+type HasUndefined<T> = undefined extends T ? true : false;
+/**
+ * Create a validator middleware
+ * @param target Target for validation
+ * @param schema Validation schema
+ * @param hook Hook for validation
+ * @returns Middleware handler
+ */
+declare function validator<Schema extends StandardSchemaV1, Target extends keyof ValidationTargets, E extends Env, P extends string, In = StandardSchemaV1.InferInput<Schema>, Out = StandardSchemaV1.InferOutput<Schema>, I extends Input = {
+    in: HasUndefined<In> extends true ? {
+        [K in Target]?: In extends ValidationTargets[K] ? In : {
+            [K2 in keyof In]?: ValidationTargets[K][K2];
+        };
+    } : {
+        [K in Target]: In extends ValidationTargets[K] ? In : {
+            [K2 in keyof In]: ValidationTargets[K][K2];
+        };
+    };
+    out: {
+        [K in Target]: Out;
+    };
+}, V extends I = I>(target: Target, schema: Schema, hook?: Hook<StandardSchemaV1.InferOutput<Schema>, E, P, Target>, options?: Record<string, unknown>): MiddlewareHandler<E, P, V>;
+/**
+ * Describe a route with OpenAPI specs.
+ * @param spec Options for describing a route
+ * @returns Middleware handler
+ */
+declare function describeRoute(spec: DescribeRouteOptions): MiddlewareHandler;
+
+/**
+ * The unique symbol for the middlewares, which makes it easier to identify them. Not meant to be used directly, unless you're creating a custom middleware.
+ */
+declare const uniqueSymbol: unique symbol;
+declare const ALLOWED_METHODS: readonly ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
+type AllowedMethods = (typeof ALLOWED_METHODS)[number];
+declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
+declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: {
+    options: SanitizedGenerateSpecOptions;
+}): OpenAPIV3_1.PathsObject<{}, {}>;
+
+type PromiseOr<T> = T | Promise<T>;
+type ResolverReturnType = ReturnType<typeof resolver>;
+type HandlerUniqueProperty = (ResolverReturnType & {
+    target: keyof ValidationTargets$1;
+    options?: Record<string, unknown>;
+}) | {
+    spec: DescribeRouteOptions;
+};
+type GenerateSpecOptions = {
+    /**
+     * Customize OpenAPI config, refers to Swagger 2.0 config
+     *
+     * @see https://swagger.io/specification/v2/
+     */
+    documentation: Omit<Partial<OpenAPIV3_1.Document>, "x-express-openapi-additional-middleware" | "x-express-openapi-validation-strict">;
+    /**
+     * Include paths which don't have the handlers.
+     * This is useful when you want to document the
+     * API without implementing it or index all the paths.
+     */
+    includeEmptyPaths: boolean;
+    /**
+     * Determine if Swagger should exclude static files.
+     *
+     * @default true
+     */
+    excludeStaticFile: boolean;
+    /**
+     * Paths to exclude from OpenAPI endpoint
+     *
+     * @default []
+     */
+    exclude: string | RegExp | Array<string | RegExp>;
+    /**
+     * Exclude methods from the specs
+     */
+    excludeMethods: AllowedMethods[];
+    /**
+     * Exclude tags from OpenAPI
+     */
+    excludeTags: string[];
+    /**
+     * Default options for `describeRoute` method
+     */
+    defaultOptions: Partial<Record<AllowedMethods | "ALL", DescribeRouteOptions>>;
+};
+type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
+type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
+type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "parameters"> & {
+    /**
+     * Pass `true` to hide route from OpenAPI/swagger document
+     */
+    hide?: boolean | ((c: Context) => boolean);
+    /**
+     * Responses of the request
+     */
+    responses?: {
+        [key: string]: (OpenAPIV3_1.ResponseObject & {
+            content?: {
+                [key: string]: Omit<OpenAPIV3_1.MediaTypeObject, "schema"> & {
+                    schema?: OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject | ResolverReturnType;
+                };
+            };
+        }) | OpenAPIV3_1.ReferenceObject;
+    };
+};
+type RegisterSchemaPathOptions = {
+    route: RouterRoute;
+    specs?: DescribeRouteOptions | Pick<OpenAPIV3_1.OperationObject, "parameters" | "requestBody">;
+    paths: Partial<OpenAPIV3_1.PathsObject>;
+};
+
+/**
+ * Generate OpenAPI specs for the given Hono instance
+ * @param hono Instance of Hono
+ * @param options Options for generating OpenAPI specs
+ * @param config Configuration for OpenAPI route handler
+ * @param Context Route context for hiding routes
+ * @returns OpenAPI specs
+ */
+declare function generateSpecs<E extends Env = BlankEnv, P extends string = string, I extends Input$1 = BlankInput, S extends Schema = BlankSchema>(hono: Hono<E, S, P>, options?: Partial<GenerateSpecOptions>, c?: Context<E, P, I>): Promise<{
+    tags: openapi_types.OpenAPIV3.TagObject[];
+    info: {
+        description: string;
+        title: string;
+        termsOfService?: string;
+        contact?: openapi_types.OpenAPIV3.ContactObject;
+        version: string;
+        summary?: string;
+        license?: OpenAPIV3_1.LicenseObject;
+    };
+    paths: {
+        [x: string]: Omit<openapi_types.OpenAPIV3.PathItemObject<{}>, "parameters" | "servers"> & {
+            servers?: OpenAPIV3_1.ServerObject[];
+            parameters?: (OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject)[];
+        } & {
+            get?: OpenAPIV3_1.OperationObject<{}>;
+            put?: OpenAPIV3_1.OperationObject<{}>;
+            post?: OpenAPIV3_1.OperationObject<{}>;
+            delete?: OpenAPIV3_1.OperationObject<{}>;
+            options?: OpenAPIV3_1.OperationObject<{}>;
+            head?: OpenAPIV3_1.OperationObject<{}>;
+            patch?: OpenAPIV3_1.OperationObject<{}>;
+            trace?: OpenAPIV3_1.OperationObject<{}>;
+        };
+    };
+    components: {
+        schemas: {
+            [x: string]: OpenAPIV3_1.SchemaObject;
+        };
+        responses?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ResponseObject>;
+        parameters?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
+        examples?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ExampleObject>;
+        requestBodies?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.RequestBodyObject>;
+        headers?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.HeaderObject>;
+        securitySchemes?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SecuritySchemeObject>;
+        links?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.LinkObject>;
+        callbacks?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.CallbackObject>;
+        pathItems?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.PathItemObject>;
+    };
+    openapi: string;
+    externalDocs?: openapi_types.OpenAPIV3.ExternalDocumentationObject;
+    security?: openapi_types.OpenAPIV3.SecurityRequirementObject[];
+    servers?: OpenAPIV3_1.ServerObject[];
+    webhooks?: Record<string, OpenAPIV3_1.PathItemObject | OpenAPIV3_1.ReferenceObject>;
+    jsonSchemaDialect?: string;
+}>;
+
+export { ALLOWED_METHODS, type AllowedMethods, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type SanitizedGenerateSpecOptions, describeRoute, generateSpecs, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };