koas-core/lib/index.d.ts

> [Koa][] + [OpenAPI Specification][] = Koas

import { PreValidatePropertyFunction, RewriteFunction, ValidatorResult } from 'jsonschema';
import { Context, Middleware } from 'koa';
import { OpenAPIV3 } from 'openapi-types';
import { JSONRefResolver } from './jsonRefs';
import { SchemaValidationError } from './validation';
export { JSONRefResolver, SchemaValidationError };
export interface KoasOptions {
    /**
     * Convert a schema validation error to an HTTP response body.
     *
     * @param error - The error that as thrown.
     * @param ctx - The Koa context.
     * @returns The HTTP response body.
     */
    onSchemaValidationError?: (error: SchemaValidationError, ctx: Context) => unknown;
}
interface ValidateOptions {
    /**
     * The error message.
     *
     * @default 'JSON schema validation failed'
     */
    message?: string;
    /**
     * A function to rewrite a property before it’s passed to the JSON schema validation
     */
    preValidateProperty?: PreValidatePropertyFunction;
    /**
     * A function to rewrite a property after has passed JSON schema validation
     */
    rewrite?: RewriteFunction;
    /**
     * The HTTP status code to set.
     *
     * @default 400
     */
    status?: number;
    /**
     * Whether or not to throw an error if the schema validation failed.
     *
     * If `false`, the `ValidatorResult` instance will be returned instead.
     *
     * @default true
     */
    throw?: boolean;
}
/**
 * A JSON schema validator function.
 *
 * @param instance - The instance to validate
 * @param schema - The JSON schema to use.
 * @param options - Additional jsonschema validation options.
 * @returns The validator result
 */
export declare type Validator = (instance: unknown, schema: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject, options?: ValidateOptions) => ValidatorResult;
declare module 'koa' {
    interface DefaultContext {
        /**
         * The OpenAPI specitic context injected by koas.
         */
        openApi?: OpenAPIContext;
    }
}
export interface OpenAPIContext {
    /**
     * The full OpenAPI document
     */
    document: OpenAPIV3.Document;
    /**
     * The OpenAPI operation object that describes the current request context.
     */
    operationObject?: OpenAPIV3.OperationObject;
    /**
     * The path item object that describes the current request context.
     */
    pathItemObject?: OpenAPIV3.PathItemObject;
    /**
     * A function to apply JSON schema validation in the context of the OpenAPI document.
     */
    validate: Validator;
}
/**
 * A function that takes Koas options and returns Koa Middleware.
 */
export declare type Plugin = (options: PluginOptions) => Middleware;
export interface PluginOptions {
    /**
     * The OpenAPI document that was given to Koas.
     */
    document: OpenAPIV3.Document;
    /**
     * Resolve a JSON pointer reference in the OpenAPI document.
     */
    resolveRef: JSONRefResolver;
    /**
     * Mark a middlere to it always runs, even if there is no matching route.
     */
    runAlways: (middleware: Middleware) => Middleware;
    /**
     * Validate an object using a JSON schema.
     *
     * References will be resolved against the OpenAPI document.
     */
    validate: Validator;
}
/**
 * Create a Koa middleware from Koas middlewares.
 *
 * @param document - The OpenAPI document from which to create an API.
 * @param middlewares - The Koas middlewares to use for creating an API.
 * @param options -  Advanced options
 * @returns Koa middleware that processes requests according the the OpenAPI document.
 */
export declare function koas(document: OpenAPIV3.Document, middlewares?: Plugin[], { onSchemaValidationError, }?: KoasOptions): Middleware;