kobp/lib/esm/src/middlewares/doc.helpers.d.ts

Koa Boilerplate with MikroORM

import type { BaseParameterObject, MediaTypeObject, OperationObject, ParameterLocation, SchemaObject, RequestBodyObject, ResponseObject } from 'openapi3-ts/oas31';
import { Middleware } from '..';
export declare const METADATA_KEYS: {
    readonly DOC_KEY: "document";
    readonly DOC_HEADERS_SHAPE_VALIDATION_KEY: "document:validate:headers";
    readonly DOC_QUERY_SHAPE_VALIDATION_KEY: "document:validate:query";
    readonly DOC_BODY_SHAPE_VALIDATION_KEY: "document:validate:body";
    readonly DOC_PARAMS_SHAPE_VALIDATION_KEY: "document:validate:param";
};
export declare const ALL_METADATA_KEYS: Set<"document" | "document:validate:headers" | "document:validate:query" | "document:validate:body" | "document:validate:param">;
/**
 * Attempt to extract schema from the SchemaObject | KobpParsable object
 *
 * NOTE: we are over simplify here as we believe that .schema would returns `OpenAPI31.SchemaObject` (or its compatible ones)
 */
export declare const extractSchema: (spec: SchemableObject, required?: boolean, mode?: 'read' | 'write') => ['zod' | 'ajv' | 'literal', SchemaObject];
/**
 * The general interface that fits `ajv-ts` which allow us to use
 * its' schema injection for documentation purpose.
 *
 * We got zod to comply with this via the optional dependency (zod-to-json-schema)
 */
export interface SchemableObject {
    schema?: any;
    /**
     * The alternative scheme that is used in readonly mode
     * useful when automatically generate an API document that emits readonly version
     */
    readonlySchema?: any;
}
/**
 * The general interface that fits `zod`, `ajv-ts`, +other for further support.
 */
export interface KobpParsable<T> extends SchemableObject {
    /**
     * A pure synchronus function that handles parsing
     * and ensure the given input object matches the required T Type
     * otherwise throws Error
     *
     * This function will ensure that;
     *
     * [1] context.query matches the T.query spec.
     * [2] context.body matches the T.body spec.
     * [3] context.params matches the T.params spec.
     *
     * @throws {Error} the message of the error will then be wrapped with KobpError
     */
    parse(object: any): T;
}
export declare class OperationDocumentBuilder {
    private doc;
    protected wrapJsonResult: boolean;
    constructor(baseDoc?: OperationObject);
    /**
     * replace the current document
     */
    from(baseDoc: OperationObject): this;
    deprecated(deprecated: boolean): this;
    describe(description: string): this;
    summary(summary: string): this;
    /**
     * Given authorization scheme MUST matched those defined in
     * the Swagger's controller (or Module's)
     *
     * @param {string} schemeName - name of the security handling example: 'bearer' | 'api-key' | 'basic'
     * @param {string[]} detail - detail of the security object
     */
    authorizeWith(schemeName: string, detail?: string[]): this;
    useHeader(map: Record<string, BaseParameterObject>): this;
    useHeader(name: string, doc: BaseParameterObject): this;
    usePath(map: Record<string, BaseParameterObject>): this;
    usePath(name: string, doc: BaseParameterObject): this;
    useQuery(map: Record<string, BaseParameterObject>): this;
    useQuery(name: string, doc: BaseParameterObject): this;
    useCookie(map: Record<string, BaseParameterObject>): this;
    useCookie(name: string, doc: BaseParameterObject): this;
    useParameters(location: ParameterLocation, nameOrMap: string | Record<string, BaseParameterObject>, doc?: BaseParameterObject): this;
    useParameter(location: ParameterLocation, name: string, doc: BaseParameterObject): this;
    /**
     * This method will override the validation body's middleware injection if used.
     */
    useBody(requestBody: RequestBodyObject): this;
    /**
     * Server successfully processed the request
     */
    onOk(schema?: any, rest?: Omit<MediaTypeObject, 'schema'>): this;
    /**
     * Server accepted the request, payload is still being processed
     */
    onOkAccepted(): this;
    /**
     * Server successfully processed the request and is not returning any content
     */
    onOkNoContent(): this;
    /**
     * Server rejected the request due to invalid user's input
     */
    onErrorBadRequest(contentOrMessage?: string | MediaTypeObject): this;
    onErrorUnauthorized(contentOrMessage?: string | MediaTypeObject): this;
    onErrorForbidden(contentOrMessage?: string | MediaTypeObject): this;
    onErrorNotFound(contentOrMessage?: string | MediaTypeObject): this;
    onErrorInternal(contentOrMessage?: string | MediaTypeObject): this;
    onErrorResponse(status: number, defaultMessage: string, contentOrMessage?: string | MediaTypeObject): this;
    onResponse(status: number, doc: ResponseObject, content?: MediaTypeObject): this;
    /**
     * useful for swagger controller to access the output document directly
     *
     * @returns {OperationObject} OpenAPI operation object
     */
    build(): OperationObject;
    middleware(): Middleware;
}