swagger-express-ts - npm Package Compare versions

Comparing version 1.0.0-alpha.5 to 1.0.0-beta.1

CHANGELOG.md

@@ -0,1 +1,86 @@
+<a name="1.0.0-beta.1"></a>
+# [1.0.0-beta.1] (2018-03-02)
+
+## Features
+
+### Authentication
+
+#### Configuration
+
+example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+#### Basic Authentication
+
+Example:
+
+```ts
+    ...
+    @ApiOperationGet( {
+        ...
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+```
+
+#### API Keys
+
+Example:
+
+```ts
+    ...
+    @ApiOperationGet( {
+        ...
+        security : {
+            apiKeyHeader : []
+        }
+    } )
+    ...
+```
+
+### Operations as deprecated
+
+Example in path:
+
+```ts
+    ...
+    @ApiPath( {
+        ...
+        deprecated: true
+    } )
+    ...
+```
+
+Example in operation:
+
+```ts
+    ...
+    @ApiOperationGet( {
+        ...
+        deprecated: true
+    } )
+    ...
+```
+
 <a name="1.0.0-alpha.5"></a>
@@ -2,0 +87,0 @@ # [1.0.0-alpha.5] (2018-02-18)

dist/api-path.decorator.d.ts

@@ -5,3 +5,7 @@ export interface IApiPathArgs {
     description?: string;
+    security?: {
+        [key: string]: any[];
+    };
+    deprecated?: boolean;
 }
 export declare function ApiPath(args: IApiPathArgs): ClassDecorator;

dist/i-api-operation-args.base.d.ts

@@ -28,11 +28,50 @@ export interface IApiOperationArgsBaseParameter {
 export interface IApiOperationArgsBase {
+    /**
+     * Define description
+     * Optional.
+     */
     description?: string;
+    /**
+     * Define summary
+     * Optional.
+     */
     summary?: string;
+    /**
+     * Define produces
+     * Optional.
+     */
     produces?: string[];
+    /**
+     * Define consumes
+     * Optional.
+     */
     consumes?: string[];
+    /**
+     * Define path
+     * Optional.
+     */
     path?: string;
+    /**
+     * Define parameters
+     * Optional.
+     */
     parameters?: IApiOperationArgsBaseParameters;
+    /**
+     * Define responses
+     */
     responses: {
         [key: string]: IApiOperationArgsBaseResponse;
     };
+    /**
+     * Define security
+     * Optional.
+     */
+    security?: {
+        [key: string]: any[];
+    };
+    /**
+     * Define deprecated
+     * Optional.
+     */
+    deprecated?: boolean;
 }

dist/i-swagger.d.ts

@@ -0,1 +1,2 @@
+import { ISwaggerSecurityDefinition } from "./swagger.builder";
 export interface ISwaggerLicense {
@@ -65,2 +66,6 @@ name: string;
     };
+    security?: {
+        [key: string]: any[];
+    }[];
+    deprecated?: boolean;
 }
@@ -111,2 +116,5 @@ export interface ISwaggerTag {
     externalDocs?: ISwaggerExternalDocs;
+    securityDefinitions?: {
+        [key: string]: ISwaggerSecurityDefinition;
+    };
 }

dist/swagger-definition.constant.d.ts

@@ -8,2 +8,3 @@ export declare class SwaggerDefinitionConstant {
     private static ARRAY;
+    private static QUERY;
     static Produce: {
@@ -55,2 +56,12 @@ XML: string;
     };
+    static Security: {
+        Type: {
+            BASIC_AUTHENTICATION: string;
+            API_KEY: string;
+        };
+        In: {
+            HEADER: string;
+            QUERY: string;
+        };
+    };
 }

dist/swagger-definition.constant.js

@@ -12,2 +12,3 @@ "use strict";
     SwaggerDefinitionConstant.ARRAY = "array";
+    SwaggerDefinitionConstant.QUERY = "query";
     SwaggerDefinitionConstant.Produce = {
@@ -47,3 +48,3 @@ XML: SwaggerDefinitionConstant.XML,
             PATH: "path",
-            QUERY: "query",
+            QUERY: SwaggerDefinitionConstant.QUERY,
             BODY: "body",
@@ -60,4 +61,14 @@ FORM_DATA: "formData"
     };
+    SwaggerDefinitionConstant.Security = {
+        Type: {
+            BASIC_AUTHENTICATION: "basic",
+            API_KEY: "apiKey"
+        },
+        In: {
+            HEADER: "header",
+            QUERY: SwaggerDefinitionConstant.QUERY
+        }
+    };
     return SwaggerDefinitionConstant;
 }());
 exports.SwaggerDefinitionConstant = SwaggerDefinitionConstant;

dist/swagger.builder.d.ts

@@ -26,2 +26,18 @@ import { ISwaggerInfo, ISwaggerExternalDocs } from "./i-swagger";
 }
+export interface ISwaggerSecurityDefinition {
+    /**
+     * Define type of security.
+     */
+    type: string;
+    /**
+     * Define where security set.
+     * Optional.
+     */
+    in?: string;
+    /**
+     * Define name of security.
+     * Optional.
+     */
+    name?: string;
+}
 export interface ISwaggerBuildDefinition {
@@ -74,3 +90,10 @@ /**
     externalDocs?: ISwaggerExternalDocs;
+    /**
+     * Define security definitions list.
+     * Optional.
+     */
+    securityDefinitions?: {
+        [key: string]: ISwaggerSecurityDefinition;
+    };
 }
 export declare function build(buildDefinition: ISwaggerBuildDefinition): void;

dist/swagger.builder.js

@@ -33,2 +33,5 @@ "use strict";
     }
+    if (buildDefinition.securityDefinitions) {
+        swagger_service_1.SwaggerService.getInstance().addSecurityDefinitions(buildDefinition.securityDefinitions);
+    }
     if (buildDefinition.models) {
@@ -35,0 +38,0 @@ var definitions = {};

dist/swagger.service.d.ts

@@ -5,2 +5,3 @@ import { ISwagger, ISwaggerInfo, ISwaggerDefinition, ISwaggerExternalDocs } from "./i-swagger";
 import { IApiOperationGetArgs } from "./api-operation-get.decorator";
+import { ISwaggerSecurityDefinition } from "./swagger.builder";
 export declare class SwaggerService {
@@ -33,7 +34,12 @@ private static instance;
     addOperationDelete(args: IApiOperationPostArgs, target: any, propertyKey: string | symbol): void;
+    addSecurityDefinitions(securityDefinitions: {
+        [key: string]: ISwaggerSecurityDefinition;
+    }): void;
     private addOperation(operation, args, target, propertyKey);
     private buildOperation(args, target, propertyKey);
+    private buildOperationSecurity(argsSecurity);
     private buildParameters(type, parameters);
     buildSwagger(): void;
+    private buildSwaggerOperation(operation, controller);
     private buildRef(definition);
 }

dist/swagger.service.js

@@ -22,2 +22,4 @@ "use strict";
     SwaggerService.prototype.resetData = function () {
+        this.controllerMap = [];
+        this.definitionsMap = {};
         this.initData();
@@ -77,5 +79,2 @@ };
         };
-        if (args.description) {
-            currentController.description = args.description;
-        }
         for (var controllerIndex in this.controllerMap) {
@@ -88,2 +87,4 @@ var controller = this.controllerMap[controllerIndex];
                 currentController.description = args.description;
+                currentController.security = args.security;
+                currentController.deprecated = args.deprecated;
             }
@@ -126,2 +127,5 @@ }
     };
+    SwaggerService.prototype.addSecurityDefinitions = function (securityDefinitions) {
+        this.data.securityDefinitions = securityDefinitions;
+    };
     SwaggerService.prototype.addOperation = function (operation, args, target, propertyKey) {
@@ -185,2 +189,5 @@ var currentController = {
         }
+        if (args.deprecated) {
+            operation.deprecated = args.deprecated;
+        }
         if (args.parameters) {
@@ -266,4 +273,17 @@ operation.parameters = [];
         }
+        if (args.security) {
+            operation.security = this.buildOperationSecurity(args.security);
+        }
         return operation;
     };
+    SwaggerService.prototype.buildOperationSecurity = function (argsSecurity) {
+        var securityToReturn = [];
+        for (var securityIndex in argsSecurity) {
+            var security = argsSecurity[securityIndex];
+            var result = {};
+            result[securityIndex] = security;
+            securityToReturn.push(result);
+        }
+        return securityToReturn;
+    };
     SwaggerService.prototype.buildParameters = function (type, parameters) {
@@ -306,50 +326,15 @@ var swaggerOperationParameter = [];
                     if (path.get) {
-                        swaggerPath.get = path.get;
-                        if (!swaggerPath.get.produces) {
-                            swaggerPath.get.produces = this.data.produces;
-                        }
-                        if (!swaggerPath.get.consumes) {
-                            swaggerPath.get.consumes = this.data.consumes;
-                        }
-                        swaggerPath.get.tags = [_.capitalize(controller.name)];
+                        swaggerPath.get = this.buildSwaggerOperation(path.get, controller);
                     }
                     if (path.post) {
-                        swaggerPath.post = path.post;
-                        if (!swaggerPath.post.produces) {
-                            swaggerPath.post.produces = this.data.produces;
-                        }
-                        if (!swaggerPath.post.consumes) {
-                            swaggerPath.post.consumes = this.data.consumes;
-                        }
-                        swaggerPath.post.tags = [_.capitalize(controller.name)];
+                        swaggerPath.post = this.buildSwaggerOperation(path.post, controller);
                     }
                     if (path.put) {
-                        swaggerPath.put = path.put;
-                        if (!swaggerPath.put.produces) {
-                            swaggerPath.put.produces = this.data.produces;
-                        }
-                        if (!swaggerPath.put.consumes) {
-                            swaggerPath.put.consumes = this.data.consumes;
-                        }
-                        swaggerPath.put.tags = [_.capitalize(controller.name)];
+                        swaggerPath.put = this.buildSwaggerOperation(path.put, controller);
                     }
                     if (path.patch) {
-                        swaggerPath.patch = path.patch;
-                        if (!swaggerPath.patch.produces) {
-                            swaggerPath.patch.produces = this.data.produces;
-                        }
-                        if (!swaggerPath.patch.consumes) {
-                            swaggerPath.patch.consumes = this.data.consumes;
-                        }
-                        swaggerPath.patch.tags = [_.capitalize(controller.name)];
+                        swaggerPath.patch = this.buildSwaggerOperation(path.patch, controller);
                     }
                     if (path.delete) {
-                        swaggerPath.delete = path.delete;
-                        if (!swaggerPath.delete.produces) {
-                            swaggerPath.delete.produces = this.data.produces;
-                        }
-                        if (!swaggerPath.delete.consumes) {
-                            swaggerPath.delete.consumes = this.data.consumes;
-                        }
-                        swaggerPath.delete.tags = [_.capitalize(controller.name)];
+                        swaggerPath.delete = this.buildSwaggerOperation(path.delete, controller);
                     }
@@ -375,2 +360,18 @@ if (path.path && path.path.length > 0) {
     };
+    SwaggerService.prototype.buildSwaggerOperation = function (operation, controller) {
+        if (_.isUndefined(operation.produces)) {
+            operation.produces = this.data.produces;
+        }
+        if (_.isUndefined(operation.consumes)) {
+            operation.consumes = this.data.consumes;
+        }
+        if (_.isUndefined(operation.security) && controller.security) {
+            operation.security = this.buildOperationSecurity(controller.security);
+        }
+        if (_.isUndefined(operation.deprecated) && controller.deprecated) {
+            operation.deprecated = controller.deprecated;
+        }
+        operation.tags = [_.capitalize(controller.name)];
+        return operation;
+    };
     SwaggerService.prototype.buildRef = function (definition) {
@@ -377,0 +378,0 @@ return "#/definitions/".concat(_.capitalize(definition));

package.json

 {
   "name": "swagger-express-ts",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-beta.1",
   "description": "Generate and serve swagger.json",
@@ -5,0 +5,0 @@ "main": "./dist/index.js",

README.md

@@ -0,1 +1,3 @@
+![](wiki/img/logo.png)
+
 # swagger-express-ts
@@ -357,4 +359,10 @@ Automatically generate and serve swagger.json v2.0.
 
-Test it on url "/api-docs/swagger". It's cool!
+Test it on url "/api-docs/swagger".
 
+![](./wiki/img/swagger-ui.png)
+
+## Project example
+
+You can quickly test swagger-express-ts with the project example [example-swagger-express-ts](https://github.com/olivierlsc/example-swagger-express-ts).
+
 ## Features and API
@@ -361,0 +369,0 @@

wiki/api-operation-delete.decorator.md

@@ -90,2 +90,61 @@ # @ApiOperationDelete(args: IApiOperationDeleteArgs)
 - Optional
-- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+
+## security: {[key: string]: any[]}
+Define security
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiOperationDelete( {
+        path : "/{id}",
+        parameters : {
+            path : {
+                id : {
+                    description : "Id of version",
+                    type : SwaggerDefinitionConstant.Parameter.Type.STRING,
+                    required : true
+                }
+            }
+        },
+        responses : {
+            200 : { description: "Success" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+}
+
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/api-operation-get.decorator.md

@@ -76,2 +76,53 @@ # @ApiOperationGet(args: IApiOperationGetArgs)
 - Optional
-- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+
+## security: {[key: string]: any[]}
+Define security
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiOperationGet( {
+        description : "Get version object",
+        summary : "Get version",
+        responses : {
+            200 : { description : "Success", isArray : true, model : "Version" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+}
+
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/api-operation-patch.decorator.md

@@ -98,2 +98,66 @@ # @ApiOperationPatch(args: IApiOperationPatchArgs)
 - Optional
-- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+
+## security: {[key: string]: any[]}
+Define security
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiOperationPatch( {
+         path : "/{id}/description",
+        description : "Patch description in version object",
+        summary : "Patch description in version",
+        parameters : {
+            path: {
+                id: {
+                    description : "Id of version",
+                    type : SwaggerDefinitionConstant.Parameter.Type.STRING,
+                    required : true
+                }
+            },
+            body : { description : "New version", required : true, model : "Version" }
+        },
+        responses : {
+            200 : { description : "Success" },
+            400 : { description : "Parameters fail" },
+            404 : { description : "Version not found" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+}
+
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/api-operation-post.decorator.md

@@ -84,2 +84,57 @@ # @ApiOperationPost(args: IApiOperationPostArgs)
 - Optional
-- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+
+## security: {[key: string]: any[]}
+Define security
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiOperationPost( {
+        description : "Post version object",
+        summary : "Post new version",
+        parameters : {
+            body : { description : "New version", required : true, model : "Version" }
+        },
+        responses : {
+            200 : { description : "Success" },
+            400 : { description : "Parameters fail" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+}
+
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/api-operation-put.decorator.md

@@ -103,2 +103,66 @@ # @ApiOperationPut(args: IApiOperationPutArgs)
 - Optional
-- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+- Default is global type list defined in ISwaggerBuildDefinition when execute [.express(options: ISwaggerExpressOptions)](./configuration.md)
+
+## security: {[key: string]: any[]}
+Define security
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiOperationPut( {
+        path : "/{id}",
+        parameters : {
+            path : {
+                id : {
+                    description : "Id of version",
+                    type : SwaggerDefinitionConstant.Parameter.Type.STRING,
+                    required : true
+                }
+            },
+            body : {
+                description : "Updated version",
+                model : "Version",
+                required : true
+            }
+        },
+        responses : {
+            200 : { model : "Version" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+}
+
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/api-path.decorator.md

@@ -37,1 +37,47 @@ # @ApiPath(args: IApiPathArgs)
 - Optional
+
+## security: {[key: string]: any[]}
+Define security to apply all operations from current path.
+- Optional
+
+Example:
+
+```ts
+    ...
+    @ApiPath( {
+        path : "/version",
+        name : "Version",
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+```
+
+### Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## deprecated: boolean
+Define deprecated
+- Optional

wiki/configuration.md

@@ -49,2 +49,55 @@ # Configuration
 Define swagger definition.
-- Required
+- Required
+
+# Authentication
+
+## Configuration
+
+Example:
+
+```ts
+    app.use( swagger.express(
+        {
+            definition : {
+                ...
+                securityDefinitions : {
+                    basicAuth : {
+                        type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
+                    },
+                    apiKeyHeader : {
+                        type: SwaggerDefinitionConstant.Security.Type.API_KEY,
+                        in: SwaggerDefinitionConstant.Security.In.HEADER,
+                        name: "apiHeader"
+                    }
+                }
+            }
+        }
+    ) );
+```
+
+## Secure controller
+
+Example:
+
+```ts
+    ...
+    @ApiPath( {
+        path : "/version",
+        name : "Version",
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+    @ApiOperationGet( {
+        description : "Get version object",
+        summary : "Get version",
+        responses : {
+            200 : { description : "Success", isArray : true, model : "Version" }
+        },
+        security : {
+            basicAuth : []
+        }
+    } )
+    ...
+```

wiki/i-swagger-build-definition.md

@@ -41,2 +41,6 @@
 Define external docs
+- Optional
+
+## securityDefinitions: {[key: string]: [ISwaggerSecurityDefinition](./i-swagger-security-definition.md)}
+Define security definitions
 - Optional

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

188293

increased by112.63%

Number of package files

54

increased by5.88%

Lines of code

1068

increased by11.02%

Number of lines in readme file

396

increased by2.06%

No dependency changes