@openapi-ts/backend/dist/openapi.d.ts

Enables easy implementions of OpenAPI REST APIs in TypeScript with full typings of schemas and operations.

import * as Ajv from 'ajv';
import * as OpenAPI from 'openapi-backend';
import { Authorizer, Awaitable, ErrorHandler, Interceptor, OperationParams, Params, RawRequest, RawResponse, RegistrationParams, Request, RequestHandler, RequestParams, Response, StringParams } from './types';
import { ParameterType } from './utils';
import { Logger } from './logger';
declare type FailStrategy = 'warn' | 'throw';
declare type ResponseTrimming = 'none' | 'failing' | 'all';
declare type HandlerData<P> = {
    res: Response;
    params: RequestParams<P>;
};
declare type OpenApiHandler<P, R> = (apiContext: OpenAPI.Context, data: HandlerData<P>) => Awaitable<R>;
export interface Options<T> {
    errorHandler?: ErrorHandler<T>;
    logger?: Logger | null;
    responseValidationStrategy?: FailStrategy;
    responseBodyTrimming?: ResponseTrimming;
    ajvOptions?: Ajv.Options;
}
/**
 * A HTTP API using an OpenAPI definition.
 * This uses the openapi-backend module to parse, route and validate requests created from events.
 *
 * @template T     Type of custom data passed to each request's params
 *
 */
export declare class OpenApi<T> {
    private interceptors;
    private apiPromises;
    private readonly paramValidator;
    readonly errorHandler: ErrorHandler<T>;
    readonly logger: Logger;
    readonly responseValidationStrategy: FailStrategy;
    readonly responseBodyTrimming: ResponseTrimming;
    readonly ajvOptions?: Ajv.Options;
    /**
     * Constructor
     * @param params Parameters
     * @param [params.errorHandler] A function creating a response from an error thrown by the API.
     * @param [params.logger] A logger, or null to suppress all logging
     * @param [params.responseValidationStrategy] How to handle validation errors on responses
     * @param [params.responseBodyTrimming] What response body trimming to perform
     * @param [params.ajvOptions] Custom AJV options
     */
    constructor({ errorHandler, logger, responseValidationStrategy, responseBodyTrimming, ajvOptions }?: Options<T>);
    private getApis;
    private createApi;
    protected parseParams(rawParams: StringParams, operation: OpenAPI.Operation, type: ParameterType, errors: Ajv.ErrorObject[]): Params;
    protected parseRequest(apiContext: OpenAPI.Context): Request;
    protected formatResponse(res: Response): RawResponse;
    private authorizeRequest;
    protected getDefaultStatusCode({ responses }: OpenAPI.Operation): number;
    protected createHandler(operationHandler: RequestHandler<OperationParams<T>>, operationId: string, authorizers: Record<string, Authorizer<T>>): OpenApiHandler<T, void>;
    protected validateResponse({ api, operation }: OpenAPI.Context, res: Response): void;
    protected handleValidationErrors(errors: Ajv.ErrorObject[] | null | undefined, title: string, strategy: FailStrategy): void;
    protected fail(message: string, strategy: FailStrategy): void;
    /**
     * Register interceptor function(s) which are executed for every request (similar to Express MW).
     * Note that the interceptors are invoked before the request is validated or routed (mapped to an operation).
     *
     * @param interceptors Interceptor functions
     * @return This instance, for chaining of calls
     */
    intercept(...interceptors: Interceptor<T>[]): this;
    /**
     * Register an OpenAPI definition and associated operation handlers.
     *
     * @param params Parameters
     * @return This instance, for chaining of calls
     */
    register({ definition, operations, authorizers, path }: RegistrationParams<T>): this;
    /**
     * Handle the given request by validating and routing it using the registered API definitions.
     * If the request is valid against the definition, the matching operation handler is invoked, and any value
     * returned from it is returned, including thrown errors.
     * If the request is invalid or no operation handler is found, an error is thrown.
     *
     * @param req Request
     * @param res Pending response (filled in by this method)
     * @param params Request params
     * @returns Empty promise if successful; rejected promise the request could not be routed
     *          or if the operation handler threw an error.
     */
    protected routeRequest(req: RawRequest, res: Response, params: RequestParams<T>): Promise<void>;
    /**
     * Handle the given request by routing it and then wrapping the result in a response.
     * If an error was thrown, the error handler function is invoked to convert it to a response.
     *
     * @param req Request
     * @param args Custom data
     * @returns Response
     */
    handleRequest(req: RawRequest, ...args: T[]): Promise<RawResponse>;
}
export {};
//# sourceMappingURL=openapi.d.ts.map