Merge pull request #19561 from bricka/swagger-tools-router-strong-typing

[swagger-tools] Adding strong typing to Swagger Router requests

types/swagger-tools/index.d.ts

@@ -5,14 +5,76 @@
 // TypeScript Version: 2.2
 
 import { NextHandleFunction } from 'connect';
-import { IncomingMessage } from 'http';
+import { IncomingMessage, ServerResponse } from 'http';
 
-export interface SwaggerRouterOptionsControllers {
-    [handlerName: string]: NextHandleFunction;
+export interface SwaggerParameterSchema {
+    name: string;
+    in: string;
 }
 
-export interface SwaggerRouterOptions {
-    controllers?: SwaggerRouterOptionsControllers | string | string[];
+export interface SwaggerRequestParameter {
+    path: string;
+    schema: SwaggerParameterSchema;
+    originalValue: any;
+    value: any;
+}
+
+export interface SwaggerRequestParameters {
+    [paramName: string]: SwaggerRequestParameter;
+}
+
+export interface Swagger12Request extends IncomingMessage {
+    swagger: {
+        api: string;
+        apiDeclaration: any;
+        apiIndex: number;
+        authorizations?: any[];
+        operation?: string;
+        operationPath?: string;
+        params: SwaggerRequestParameters;
+        resourceIndex: number;
+        resourceListing: any;
+    };
+}
+
+export type SwaggerRouter12HandlerFunction = (req: Swagger12Request, res: ServerResponse, next: (arg?: any) => void) => void;
+
+export interface SwaggerRouter12OptionsControllers {
+    [handlerName: string]: SwaggerRouter12HandlerFunction;
+}
+
+export interface SwaggerRouter12Options {
+    controllers?: SwaggerRouter12OptionsControllers | string | string[];
+    ignoreMissingHandlers?: boolean;
+    useStubs?: boolean;
+}
+
+export interface OperationParameter {
+    path: string;
+    schema: SwaggerParameterSchema;
+}
+
+export interface Swagger20Request extends IncomingMessage {
+    swagger: {
+        apiPath: string;
+        operation?: string;
+        operationPath?: string;
+        operationParameters?: OperationParameter[];
+        path: string;
+        params: SwaggerRequestParameters;
+        security: any[];
+        swaggerObject: any;
+    };
+}
+
+export type SwaggerRouter20HandlerFunction = (req: Swagger20Request, res: ServerResponse, next: (arg?: any) => void) => void;
+
+export interface SwaggerRouter20OptionsControllers {
+    [handlerName: string]: SwaggerRouter20HandlerFunction;
+}
+
+export interface SwaggerRouter20Options {
+    controllers?: SwaggerRouter20OptionsControllers | string | string[];
     ignoreMissingHandlers?: boolean;
     useStubs?: boolean;
 }
@@ -50,16 +112,17 @@ export interface SwaggerValidatorOptions {
 
 export interface Middleware {
     swaggerMetadata(): NextHandleFunction;
-    swaggerRouter(options?: SwaggerRouterOptions): NextHandleFunction;
     swaggerSecurity(options?: SwaggerSecurityOptions): NextHandleFunction;
     swaggerValidator(options?: SwaggerValidatorOptions): NextHandleFunction;
 }
 
 export interface Middleware12 extends Middleware {
+    swaggerRouter(options?: SwaggerRouter12Options): NextHandleFunction;
     swaggerUi(apiDeclarations: SwaggerUi12ApiDeclarations, options?: SwaggerUiOptions): NextHandleFunction;
 }
 
 export interface Middleware20 extends Middleware {
+    swaggerRouter(options?: SwaggerRouter20Options): NextHandleFunction;
     swaggerUi(options?: SwaggerUiOptions): NextHandleFunction;
 }
 

types/swagger-tools/swagger-tools-tests.ts

@@ -34,6 +34,27 @@ swaggerTools.initializeMiddleware(swaggerDoc20, middleware => {
     // Route validated requests to appropriate controller
     app.use(middleware.swaggerRouter(options));
 
+    // Test passing in the handlers directly
+    app.use(middleware.swaggerRouter({
+        controllers: {
+            foo_bar: (req, res, next) => {
+                console.log(req.swagger.apiPath);
+                console.log(req.swagger.operation);
+                console.log(req.swagger.operationParameters);
+                console.log(req.swagger.operationPath);
+                console.log(req.swagger.path);
+                console.log(req.swagger.security);
+                console.log(req.swagger.swaggerObject);
+
+                console.log(req.swagger.params.location.value);
+                console.log(req.swagger.params.unit.value);
+
+                res.setHeader('Content-Type', 'application/json');
+                res.end([ 'foo', 0 ]);
+            },
+        }
+    }));
+
     // Serve the Swagger documents and Swagger UI
     app.use(middleware.swaggerUi(swaggerUiOptions));
     app.use(middleware.swaggerUi());
@@ -66,6 +87,27 @@ swaggerTools.initializeMiddleware(apiDoc12, apiDeclarations, middleware => {
     // Route validated requests to appropriate controller
     app.use(middleware.swaggerRouter(options));
 
+    // Test passing in the handlers directly
+    app.use(middleware.swaggerRouter({
+        controllers: {
+            foo_bar: (req, res, next) => {
+                console.log(req.swagger.api);
+                console.log(req.swagger.apiDeclaration);
+                console.log(req.swagger.apiIndex);
+                console.log(req.swagger.operation);
+                console.log(req.swagger.operationPath);
+                console.log(req.swagger.resourceIndex);
+                console.log(req.swagger.resourceListing);
+
+                console.log(req.swagger.params.location.value);
+                console.log(req.swagger.params.unit.value);
+
+                res.setHeader('Content-Type', 'application/json');
+                res.end([ 'foo', 0 ]);
+            },
+        }
+    }));
+
     // Serve the Swagger documents and Swagger UI
     app.use(middleware.swaggerUi({
         '/weather': apiDeclarations[0]