DefinitelyTyped/express-openapi/index.d.ts

// Type definitions for express-openapi 0.11.x
// Project: https://github.com/kogosoftwarellc/express-openapi
// Definitions by: TANAKA Koichi <https://github.com/mugeso/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/* =================== USAGE ===================
 import express = require('express');
 import bodyParser = require('body-parser');
 import openapi = require('express-openapi');
 import cors = require('cors');

 var app = express();
 app.use(cors());
 app.use(bodyParser.json());

 var api: openapi.InitializedApi;
 api = openapi.initialize({
 apiDoc: require('./api-doc.js'),
 app: app,
 routes: './api-routes'
 });

 app.use(function(err, req, res, next) {
 res.status(err.status).json(err);
 });

 app.listen(3000);
 =============================================== */




import express = require('express');

export declare function initialize(args: Args): InitializedApi;

export interface InitializedApi {
    apiDoc: OpenApi.ApiDefinition;
}

export declare namespace OpenApi {
    export interface ApiDefinition {
        swagger: string;
        info: InfoObject;
        host?: string;
        basePath?: string;
        schemes?: string[];
        consumes?: MimeTypes;
        produces?: MimeTypes;
        paths: PathsObject;
        definitions?: DefinitionsObject;
        parameters?: ParametersDefinitionsObject;
        responses?: ResponsesDefinitionsObject;
        securityDefinitions?: SecurityDefinitionsObject;
        security?: SecurityRequirementObject[];
        tags?: TagObject[];
        externalDocs?: ExternalDocumentationObject;
    }

    type MimeTypes = string[];

    export interface InfoObject {
        title: string;
        description?: string;
        termsOfService?: string;
        contact?: ContactObject;
        license?: LicenseObject;
        version: string;
    }

    export interface ContactObject {
        name?: string;
        url?: string;
        email?: string;
    }

    export interface LicenseObject {
        name: string;
        url?: string;
    }

    export interface PathsObject {
        [index: string]: PathItemObject | any;
    }

    export interface PathItemObject {
        $ref?: string;
        get?: OperationObject;
        put?: OperationObject;
        post?: OperationObject;
        'delete'?: OperationObject;
        options?: OperationObject;
        head?: OperationObject;
        patch?: OperationObject;
        parameters?: Parameters;
    }

    export interface OperationObject {
        tags?: string[];
        summary?: string;
        description?: string;
        externalDocs?: ExternalDocumentationObject;
        operationId?: string;
        consumes?: MimeTypes;
        produces?: MimeTypes;
        parameters?: Parameters;
        responses: ResponsesObject;
        schemes?: string[];
        deprecated?: boolean;
        security?: SecurityRequirementObject[];
        [index: string]: any;
    }

    export interface DefinitionsObject {
        [index: string]: SchemaObject;
    }

    export interface ResponsesObject {
        [index: string]: Response | any;
        default: Response;
    }

    type Response = ResponseObject | ReferenceObject;

    export interface ResponsesDefinitionsObject {
        [index: string]: ResponseObject;
    }

    export interface ResponseObject {
        description: string;
        schema?: Schema;
        headers?: HeadersObject;
        examples?: ExampleObject;
    }

    export interface HeadersObject {
        [index: string]: HeaderObject;
    }

    export interface HeaderObject extends ItemsObject {
    }

    export interface ExampleObject {
        [index: string]: any;
    }

    export interface SecurityDefinitionsObject {
        [index: string]: SecuritySchemeObject;
    }

    export interface SecuritySchemeObject {
        type: string;
        description?: string;
        name: string;
        in: string;
        flow: string;
        authorizationUrl: string;
        tokenUrl: string;
        scopes: ScopesObject;
    }

    export interface ScopesObject {
        [index: string]: any;
    }

    export interface SecurityRequirementObject {
        [index: string]: string[];
    }

    export interface TagObject {
        name: string;
        description?: string;
        externalDocs?: ExternalDocumentationObject;
    }

    export interface ItemsObject {
        type: string;
        format?: string;
        items?: ItemsObject;
        collectionFormat?: string;
        default?: any;
        maximum?: number;
        exclusiveMaximum?: boolean;
        minimum?: number;
        exclusiveMinimum?: boolean;
        maxLength?: number;
        minLength?: number;
        pattern?: string;
        maxItems?: number;
        minItems?: number;
        uniqueItems?: boolean;
        enum?: any[];
        multipleOf?: number;
    }

    export interface ParametersDefinitionsObject {
        [index: string]: ParameterObject;
    }

    type Parameters = (ReferenceObject | Parameter)[];

    type Parameter = (InBodyParameterObject | GeneralParameterObject);

    interface ParameterObject {
        name: string;
        in: string;
        description?: string;
        required?: boolean;
    }

    export interface InBodyParameterObject extends ParameterObject {
        schema: Schema;
    }

    export interface GeneralParameterObject extends ParameterObject, ItemsObject {
        allowEmptyValue?: boolean;
    }

    export interface ReferenceObject {
        $ref: string;
    }

    export interface ExternalDocumentationObject {
        [index: string]: any;
        description?: string;
        url: string;
    }

    type Schema = SchemaObject | ReferenceObject;

    export interface SchemaObject extends IJsonSchema {
        [index: string]: any;
        discriminator?: string;
        readOnly?: boolean;
        xml?: XMLObject;
        externalDocs: ExternalDocumentationObject;
        example: any;
    }

    export interface XMLObject {
        [index: string]: any;
        name?: string;
        namespace?: string;
        prefix?: string;
        attribute?: boolean;
        wrapped?: boolean;
    }
}

export interface Args {
    apiDoc: OpenApi.ApiDefinition;
    app: express.Application;
    routes: string;
    docPath: string;
    errorTransformer(openapiError: OpenapiError, jsonschemaError: JsonschemaError): any;
    exposeApiDocs: boolean;
    validateApiDoc: boolean;
    customFormats: CustomFormats;
}

export interface OperationFunction extends express.RequestHandler {
    apiDoc?: OpenApi.OperationObject;
}

export interface OperationHandlerArray {
    apiDoc?: OpenApi.OperationObject;
    [index: number]: express.RequestHandler;
}

export type Operation = OperationFunction | OperationHandlerArray;

export interface PathModule {
    parameters?: OpenApi.Parameters;
    get?: Operation;
    put?: Operation;
    post?: Operation;
    delete?: Operation;
    patch?: Operation;
    options?: Operation;
    head?: Operation;
}

export interface OpenapiError {
    errorCode: string;
    location: string;
    message: string;
    path: string;
}

export interface CustomFormats {
    [index: string]: CustomFormatValidator;
}

// Following 2 interfaces are part of jsonschema package.
interface JsonschemaError {
    property: string;
    message: string;
    schema: string | IJsonSchema;
    instance: any;
    name: string;
    argument: any;
    stack: string;
    toString(): string;
}

interface CustomFormatValidator {
    (input: any): boolean;
}

interface IJsonSchema {
    id?: string;
    $schema?: string;
    title?: string;
    description?: string;
    multipleOf?: number;
    maximum?: number;
    exclusiveMaximum?: boolean;
    minimum?: number;
    exclusiveMinimum?: boolean;
    maxLength?: number;
    minLength?: number;
    pattern?: string;
    additionalItems?: boolean | IJsonSchema;
    items?: IJsonSchema | IJsonSchema[];
    maxItems?: number;
    minItems?: number;
    uniqueItems?: boolean;
    maxProperties?: number;
    minProperties?: number;
    required?: string[];
    additionalProperties?: boolean | IJsonSchema;
    definitions?: {
        [name: string]: IJsonSchema;
    };
    properties?: {
        [name: string]: IJsonSchema;
    };
    patternProperties?: {
        [name: string]: IJsonSchema;
    };
    dependencies?: {
        [name: string]: IJsonSchema | string[];
    };
    enum?: any[];
    type?: string | string[];
    allOf?: IJsonSchema[];
    anyOf?: IJsonSchema[];
    oneOf?: IJsonSchema[];
    not?: IJsonSchema;
}