mirror of
https://github.com/gosticks/DefinitelyTyped.git
synced 2025-10-16 12:05:41 +00:00
298 lines
10 KiB
TypeScript
298 lines
10 KiB
TypeScript
// Type definitions for swagger-node-runner 0.6
|
|
// Project: https://github.com/theganyo/swagger-node-runner
|
|
// Definitions by: Michael Mrowetz <https://github.com/micmro>
|
|
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
|
// TypeScript Version: 2.4
|
|
|
|
/* =================== USAGE ===================
|
|
|
|
import * as SwaggerNodeRunner from "swagger-node-runner";
|
|
import * as express from "express";
|
|
|
|
let app = express();
|
|
let config = {
|
|
appRoot: __dirname
|
|
};
|
|
|
|
SwaggerNodeRunner.create(config, (err, runner) => {
|
|
if (err) {
|
|
throw err; // or handle error
|
|
}
|
|
let middleware = runner.expressMiddleware();
|
|
middleware.register(app);
|
|
|
|
const port = process.env.PORT || 10010;
|
|
app.listen(port);
|
|
|
|
console.log('try this:\ncurl http://127.0.0.1:' + port + '/v1/hello?name=Scott');
|
|
});
|
|
|
|
=============================================== */
|
|
|
|
/// <reference types="node"/>
|
|
|
|
import { Express, NextFunction } from "express";
|
|
import { Spec } from "swagger-schema-official";
|
|
import { EventEmitter } from "events";
|
|
import * as Hapi from "hapi";
|
|
import * as Restify from "restify";
|
|
import { OutgoingHttpHeaders } from "http";
|
|
|
|
/**
|
|
* Config object for SwaggerNodeRunner
|
|
*/
|
|
export interface Config {
|
|
/**
|
|
* Path to app
|
|
*/
|
|
appRoot: string;
|
|
/**
|
|
* If `true` API is in mock mode
|
|
*
|
|
* default is `false`
|
|
*/
|
|
mockMode?: boolean;
|
|
/**
|
|
* If `true` resonse is validated
|
|
*
|
|
* default is `true`
|
|
*/
|
|
validateResponse?: boolean;
|
|
/**
|
|
* Sets `NODE_CONFIG_DIR` env if not set yet
|
|
*/
|
|
configDir?: string;
|
|
/**
|
|
* Swagger controller directories
|
|
*
|
|
* default is array with `/api/controllers` relative to `appRoot`
|
|
*/
|
|
controllersDirs?: string[];
|
|
/**
|
|
* Swagger mock controller directories
|
|
*
|
|
* default is array with `/api/mocks` relative to `appRoot`
|
|
*/
|
|
mockControllersDirs?: string[];
|
|
/**
|
|
* Used for Bagpipes library
|
|
*
|
|
* default is `[api/fittings]`
|
|
*/
|
|
fittingsDirs?: string[];
|
|
/**
|
|
* Define Middleware for using Swagger security information to authenticate requests. Part of _swagger-tools_
|
|
*
|
|
* default is `undefined`
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-security.js|Github Source}
|
|
*/
|
|
swaggerSecurityHandlers?: SwaggerSecurityHandlers;
|
|
/**
|
|
* Used for Bagpipes library
|
|
*
|
|
* @se @link{https://github.com/apigee-127/bagpipes|Github Source}
|
|
*/
|
|
bagpipes?: any;
|
|
/**
|
|
* default is `null`
|
|
*/
|
|
defaultPipe?: string;
|
|
/**
|
|
* default is `swagger_controllers`
|
|
*/
|
|
swaggerControllerPipe?: string;
|
|
/**
|
|
* Absolute path to swagger.yml file, if not set default value is used.
|
|
*/
|
|
swaggerFile?: string;
|
|
}
|
|
|
|
/** Internally stored version of config */
|
|
export interface ConfigInternal {
|
|
/** Config of SwaggerNodeRunner */
|
|
swagger?: Config;
|
|
}
|
|
|
|
/** Middleware used by `swagger-tools` */
|
|
export type SwaggerToolsMiddleware = (req: any, res: any, next: any) => any;
|
|
|
|
/**
|
|
* @param callback - Error is returned if request is unauthorized.
|
|
* The Error may include "message", and "code" fields to be conveyed to the client in the response body and a
|
|
* "headers" field containing an object representing headers to be set on the response to the client.
|
|
* In addition, if the Error has a statusCode field, the response statusCode will be set to match -
|
|
* otherwise, the statusCode will be set to 403.
|
|
*/
|
|
export interface SwaggerToolsSecurityHandlerCallbackError {
|
|
code?: string;
|
|
headers?: OutgoingHttpHeaders;
|
|
message?: string;
|
|
statusCode?: number;
|
|
}
|
|
export type SwaggerToolsSecurityHandler = (request: any, securityDefinition: any, scopes: any, callback: (err?: Error | SwaggerToolsSecurityHandlerCallbackError, result?: any) => void) => void;
|
|
|
|
/**
|
|
* The keys match SecurityDefinition names and the associated values are functions that accept the following parameters:
|
|
* `(request, securityDefinition, scopes, callback)`
|
|
*/
|
|
export interface SwaggerSecurityHandlers {
|
|
[name: string]: SwaggerToolsSecurityHandler;
|
|
}
|
|
|
|
/**
|
|
* Runner instance
|
|
*/
|
|
export interface Runner extends EventEmitter {
|
|
/** Resolves path (relative to `config.appRoot`) */
|
|
resolveAppPath(...to: any[]): string;
|
|
defaultErrorHandler(): any;
|
|
/** Fetch a _bagpipe_ pipe */
|
|
getPipe(req: { swagger: { path: any } }): any;
|
|
config: ConfigInternal;
|
|
/**
|
|
* Current OpenAPI Specification (formaly known as Swagger RESTful API Documentation Specification)
|
|
* @see {@link http://swagger.io/specification/|Swagger Specs}
|
|
*/
|
|
swagger: Spec;
|
|
/**
|
|
* References to Swagger Tools Midleware (from _swagger-tools_ module) *
|
|
* @see {@link https://github.com/apigee-127/swagger-tools|Github Source}
|
|
*/
|
|
swaggerTools: {
|
|
/**
|
|
* Middleware for providing Swagger information to downstream middleware and request handlers.
|
|
*
|
|
* @param rlOrSO - The Resource Listing (Swagger 1.2) or Swagger Object (Swagger 2.0)
|
|
* @param apiDeclarations - The array of API Declarations (Swagger 1.2)
|
|
*
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-metadata.js|Git Source}
|
|
*/
|
|
swaggerMetadata(rlOrSO: any, apiDeclarations: any[]): SwaggerToolsMiddleware
|
|
/**
|
|
* Middleware for using Swagger information to route requests to handlers.
|
|
* @param [] options - The configuration options
|
|
*
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/docs/Middleware.md#swaggerrouteroptions|Docs}
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-router.js|Github Source}
|
|
*/
|
|
swaggerRouter(options?: any): SwaggerToolsMiddleware
|
|
/**
|
|
* Middleware for using Swagger security information to authenticate requests.
|
|
* @param [] options - The configuration options
|
|
*
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-security.js|Github Source}
|
|
*/
|
|
swaggerSecurity(options?: SwaggerSecurityHandlers): SwaggerToolsMiddleware
|
|
/**
|
|
* Middleware for serving the Swagger documents and Swagger UI.
|
|
*
|
|
* @param rlOrSO - The Resource Listing (Swagger 1.2) or Swagger Object (Swagger 2.0)
|
|
* @param apiDeclarations - The array of API Declarations (Swagger 1.2)
|
|
* @param [] options - The configuration options
|
|
*
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-ui.js|Github Source}
|
|
*/
|
|
swaggerUi(rlOrSO: any, apiDeclarations: any[], options?: any): SwaggerToolsMiddleware
|
|
/**
|
|
* Middleware for using Swagger information to validate API requests/responses.type
|
|
* @param [] options - The configuration options
|
|
*
|
|
* @see {@link https://github.com/apigee-127/swagger-tools/blob/master/middleware/swagger-validator.js|Github Source}
|
|
*/
|
|
swaggerValidator(options?: any): SwaggerToolsMiddleware
|
|
};
|
|
swaggerSecurityHandlers: SwaggerSecurityHandlers | undefined;
|
|
/**
|
|
* Nested Key Value description for _backpipes_ module
|
|
* @see {@link https://github.com/apigee-127/bagpipes#pipes|Github Source}
|
|
*/
|
|
bagpipes: { [name: string]: any };
|
|
/** Create new Connect middleware */
|
|
connectMiddleware(): ConnectMiddleware;
|
|
/** Create new Express middleware */
|
|
expressMiddleware(): ExpressMiddleware;
|
|
/** Create new Restify middleware */
|
|
restifyMiddleware(): RestifyMiddleware;
|
|
/** Create new Sails middleware */
|
|
sailsMiddleware(): SailsMiddleware;
|
|
/** Create new Hapi middleware */
|
|
hapiMiddleware(): HapiMiddleware;
|
|
}
|
|
|
|
/** base used by all middleware versions */
|
|
export interface Middleware {
|
|
/** Back-reference to `swagger-node-runner`s `Runner` that has created this middleware */
|
|
runner: Runner;
|
|
}
|
|
|
|
/** Connect/Express specific Middleware */
|
|
export interface ConnectMiddleware extends Middleware {
|
|
middleware(): (req: Express.Request, res: Express.Response, next: NextFunction) => void;
|
|
/** Register this Middleware with `app` */
|
|
register(app: Express.Application): void;
|
|
}
|
|
/**
|
|
* Express specific Middleware
|
|
*
|
|
* _Alias for `ConnectMiddleware`_
|
|
*/
|
|
// tslint:disable-next-line:no-empty-interface
|
|
export interface ExpressMiddleware extends ConnectMiddleware { }
|
|
|
|
/** Sails specific Middleware */
|
|
export interface SailsMiddleware extends Middleware {
|
|
/** Express style middleware */
|
|
chain(): (req: Express.Request, res: Express.Response, next: NextFunction) => void;
|
|
}
|
|
|
|
/** Hapi specific Middleware */
|
|
export interface HapiMiddleware extends Middleware {
|
|
/** Back-reference to Config object of `Runner` that has created this middleware */
|
|
config: ConfigInternal;
|
|
|
|
/** Hapi Plugin */
|
|
plugin: {
|
|
/**
|
|
* Hapi plugin `register` implementation.
|
|
* @see {@link https://hapijs.com/tutorials/plugins|Hapi Docs}
|
|
*/
|
|
register: {
|
|
/**
|
|
* Registers Plugin with `onRequest` and traces `request-error` callbacks
|
|
* *
|
|
* @param server - Hapi server
|
|
* @param options - options for plugin (not used in the moment)
|
|
* @param next - callback called when register is done
|
|
*/
|
|
(server: Hapi.Server, options: any, next: () => void): void;
|
|
/** Object attached to `register` function to provide hapi with some additional information about the plugin */
|
|
attributes: {
|
|
/** Name of Plugin (e.g. `swagger-node-runner`) */
|
|
name: string
|
|
/** Version of Plugin */
|
|
version: string
|
|
}
|
|
}
|
|
};
|
|
}
|
|
|
|
/** Restify specific Middleware */
|
|
export interface RestifyMiddleware extends Middleware {
|
|
/** Register this Middleware with `app` */
|
|
register(app: Restify.Server): void;
|
|
}
|
|
|
|
/**
|
|
* Create new SwaggerNodeRunner Instance
|
|
*
|
|
* SwaggerNode config priority:
|
|
* 1. `swagger_**` environment vars
|
|
* 2. `config` passed to `create()`
|
|
* 3. read from swagger node in `default.yaml` in config directory
|
|
* 4. defaults
|
|
*
|
|
* @param config - Configuration for `Runner`
|
|
* @param runner - This Callback is called when the `Runner` has been instantiated
|
|
*/
|
|
export function create(config: Config, cb: (err: Error | undefined, runner: Runner) => void): void;
|