Merge branch 'master' of https://github.com/thiagobustamante/typescript-rest-swagger

Author: Teddy Chambard

README.MD

@@ -147,7 +147,9 @@ class PeopleService {
 
 #### @Security
 
-Add a security constraint to method generated docs, refering the security name from securityDefinitions
+Add a security constraint to method generated docs, referencing the security name from securityDefinitions.
+`@Security` can be used at the controller and method level; if defined on both, method security overwrites controller security.
+Multiple security schemes may be specified to require all of them.
 
 ```typescript
 @Path('people')

src/metadata/controllerGenerator.ts

@@ -84,15 +84,10 @@ export class ControllerGenerator {
 
         const securityDecorators = getDecorators(this.node, decorator => decorator.text === 'Security');
         if (!securityDecorators || !securityDecorators.length) { return undefined; }
-        if (securityDecorators.length > 1) {
-            throw new Error(`Only one Security decorator allowed in '${this.node.name.text}' controller.`);
-        }
-
-        const d = securityDecorators[0];
 
-        return {
+        return securityDecorators.map(d => ({
             name: d.arguments[0],
             scopes: d.arguments[1] ? (d.arguments[1] as any).elements.map((e: any) => e.text) : undefined
-        };
+        }));
     }
 }

src/metadata/metadataGenerator.ts

@@ -94,7 +94,7 @@ export interface Controller {
     consumes: string[];
     produces: string[];
     tags: string[];
-    security?: Security;
+    security?: Security[];
 }
 
 export interface Method {
@@ -107,7 +107,7 @@ export interface Method {
     type: Type;
     tags: string[];
     responses: ResponseType[];
-    security?: Security;
+    security?: Security[];
     summary?: string;
     consumes: string[];
     produces: string[];

src/metadata/methodGenerator.ts

@@ -219,16 +219,11 @@ export class MethodGenerator {
     private getMethodSecurity() {
         const securityDecorators = getDecorators(this.node, decorator => decorator.text === 'Security');
         if (!securityDecorators || !securityDecorators.length) { return undefined; }
-        if (securityDecorators.length > 1) {
-            throw new Error(`Only one Security decorator allowed in '${this.getCurrentLocation}' method.`);
-        }
-
-        const d = securityDecorators[0];
 
-        return {
+        return securityDecorators.map(d => ({
             name: d.arguments[0],
             scopes: d.arguments[1] ? (d.arguments[1] as any).elements.map((e: any) => e.text) : undefined
-        };
+        }));
     }
 
     private getInitializerValue(initializer: any) {

src/metadata/resolveType.ts

@@ -291,7 +291,7 @@ function getAnyTypeName(typeNode: ts.TypeNode): string {
 
     if (typeNode.kind === ts.SyntaxKind.ArrayType) {
         const arrayType = typeNode as ts.ArrayTypeNode;
-        return getAnyTypeName(arrayType.elementType) + '[]';
+        return getAnyTypeName(arrayType.elementType) + 'Array';
     }
 
     if ((typeNode.kind === ts.SyntaxKind.UnionType) || (typeNode.kind === ts.SyntaxKind.AnyKeyword)) {

src/swagger/generator.ts

@@ -120,9 +120,9 @@ export class SpecGenerator {
         if (method.deprecated) { pathMethod.deprecated = method.deprecated; }
         if (method.tags.length) { pathMethod.tags = method.tags; }
         if (method.security) {
-            const security: any = {};
-            security[method.security.name] = method.security.scopes ? method.security.scopes : [];
-            pathMethod.security = [security];
+            pathMethod.security = method.security.map(s => ({
+                [s.name]: s.scopes || []
+            }));
         }
         this.handleMethodConsumes(method, pathMethod);
 

test/data/apis.ts

@@ -1,11 +1,13 @@
 'use strict';
 
-import {Path, Server, GET, POST, PUT, DELETE, HttpMethod,
-        PathParam, QueryParam, CookieParam, HeaderParam,
-        FormParam, Param, Context, ServiceContext, ContextRequest,
-        ContextResponse, ContextLanguage, ContextAccept,
-        ContextNext, AcceptLanguage, Accept, FileParam,
-        Errors, Return, BodyOptions} from 'typescript-rest';
+import {
+    Path, Server, GET, POST, PUT, DELETE, HttpMethod,
+    PathParam, QueryParam, CookieParam, HeaderParam,
+    FormParam, Param, Context, ServiceContext, ContextRequest,
+    ContextResponse, ContextLanguage, ContextAccept,
+    ContextNext, AcceptLanguage, Accept, FileParam,
+    Errors, Return, BodyOptions
+} from 'typescript-rest';
 
 import * as swagger from '../../src/decorators';
 
@@ -27,13 +29,13 @@ export class MyService {
     @swagger.Response<string>(500, 'There was an unexpected error.')
     @GET
     @Accept('text/html')
-    test( ): string {
+    test(): string {
         return 'OK';
     }
 
     /**
-     * Esta eh a da classe
-     * @param test Esta eh a description do param teste
+     * This is the method description
+     * @param test This is the test param description
      */
     @GET
     @Path('secondpath')
@@ -42,11 +44,11 @@ export class MyService {
     })
     @swagger.Response<Person>(200, 'The success test.')
     test2(
-        @QueryParam('testRequired')test: string,
-        @QueryParam('testDefault')test2: string = 'value',
-        @QueryParam('testOptional')test3?: string
+        @QueryParam('testRequired') test: string,
+        @QueryParam('testDefault') test2: string = 'value',
+        @QueryParam('testOptional') test3?: string
     ): Person {
-        return {name: 'OK'};
+        return { name: 'OK' };
     }
 
     @POST
@@ -88,7 +90,7 @@ export class MyService {
 class BaseService {
     @DELETE
     @Path(':id')
-    testDelete( @PathParam('id')id: string): Promise<void> {
+    testDelete(@PathParam('id') id: string): Promise<void> {
         return new Promise<void>((resolve, reject) => {
             resolve();
         });
@@ -103,9 +105,9 @@ export class PromiseService extends BaseService {
      */
     @swagger.Response<string>(401, 'Unauthorized')
     @GET
-    test( @QueryParam('testParam')test?: string ): Promise<Person> {
+    test(@QueryParam('testParam') test?: string): Promise<Person> {
         return new Promise<Person>((resolve, reject) => {
-            resolve({name: 'OK'});
+            resolve({ name: 'OK' });
         });
     }
 
@@ -114,7 +116,7 @@ export class PromiseService extends BaseService {
     @swagger.Example<Person>({ name: 'Test Person' })
     @GET
     @Path(':id')
-    testGetSingle( @PathParam('id') id: string ): Promise<Person> {
+    testGetSingle(@PathParam('id') id: string): Promise<Person> {
         return new Promise<Person>((resolve, reject) => {
             resolve({ name: 'OK' });
         });
@@ -124,27 +126,27 @@ export class PromiseService extends BaseService {
     @swagger.Response<string>(401, 'Unauthorized')
     @swagger.Example<Person>({ name: 'Example Person' }) // NOTE: this is here to test that it doesn't overwrite the example in the @Response above
     @POST
-    testPost( obj: Person ): Promise<Return.NewResource<Person>> {
+    testPost(obj: Person): Promise<Return.NewResource<Person>> {
         return new Promise<Return.NewResource<Person>>((resolve, reject) => {
-            resolve(new Return.NewResource<Person>('id', {name: 'OK'}));
+            resolve(new Return.NewResource<Person>('id', { name: 'OK' }));
         });
     }
 
     @GET
     @Path('myFile')
     @swagger.Produces('application/pdf')
-    testFile( @QueryParam('testParam')test?: string ): Promise<Return.DownloadBinaryData> {
+    testFile(@QueryParam('testParam') test?: string): Promise<Return.DownloadBinaryData> {
         return new Promise<Return.DownloadBinaryData>((resolve, reject) => {
             resolve(null);
         });
     }
 }
 
 export class BasicModel {
-  id: number;
+    id: number;
 }
 
-export class BasicEndpoint <T extends BasicModel>  {
+export class BasicEndpoint<T extends BasicModel>  {
 
     protected list(@QueryParam('full') full?: boolean): Promise<Array<T>> {
         return new Promise((resolve, reject) => {
@@ -194,7 +196,7 @@ export class DerivedEndpoint extends BasicEndpoint<MyDatatype> {
     @GET
     @Path(':param')
     protected test(@PathParam('param') param: string): Promise<void> {
-        return new Promise<void>((resolve, reject)=> {
+        return new Promise<void>((resolve, reject) => {
             // content
         });
     }
@@ -214,7 +216,7 @@ export class DerivedEndpoint2 {
     @GET
     @Path(':param')
     protected test(@PathParam('param') param: string): Promise<MyDatatype2> {
-        return new Promise<MyDatatype2>((resolve, reject)=> {
+        return new Promise<MyDatatype2>((resolve, reject) => {
             // content
         });
     }
@@ -251,12 +253,16 @@ export class TypeEndpoint {
     @GET
     @Path(':param')
     test(@PathParam('param') param: string): Promise<SimpleHelloType> {
-        return new Promise<MyDatatype2>((resolve, reject)=> {
+        return new Promise<MyDatatype2>((resolve, reject) => {
             // content
         });
     }
 }
 
+export interface ResponseBody<T> {
+    data: T;
+}
+
 export class PrimitiveClassModel {
     /**
      * An integer
@@ -317,14 +323,20 @@ export class PrimitiveEndpoint {
     getById(@PathParam('id') @swagger.IsLong id: number) {
         // ...
     }
+
+    @Path('/array')
+    @GET
+    getArray(): ResponseBody<string[]> {
+        return { data: ['hello', 'world'] };
+    }
 }
 
 @Path('parameterized/:objectId')
 export class ParameterizedEndpoint {
 
     @Path('/test')
     @GET
-    test(@PathParam('objectId')objectId: string): PrimitiveClassModel {
+    test(@PathParam('objectId') objectId: string): PrimitiveClassModel {
         return new PrimitiveClassModel();
     }
 }
@@ -348,3 +360,28 @@ export class AbstractEntityEndpoint {
         return new NamedEntity();
     }
 }
+
+@Path('secure')
+@swagger.Security('access_token')
+export class SecureEndpoint {
+    @GET
+    get(): string {
+        return 'Access Granted';
+    }
+
+    @POST
+    @swagger.Security('user_email')
+    post(): string {
+        return 'Posted';
+    }
+}
+
+@Path('supersecure')
+@swagger.Security('access_token')
+@swagger.Security('user_email')
+export class SuperSecureEndpoint {
+    @GET
+    get(): string {
+        return 'Access Granted';
+    }
+}

test/data/swagger.json

@@ -14,6 +14,16 @@
                 "type": "apiKey",
                 "name": "access_token",
                 "in": "query"
+            },
+            "access_token": {
+                "type": "apiKey",
+                "name": "authorization",
+                "in": "header"
+            },
+            "user_email": {
+                "type": "apiKey",
+                "name": "x-user-email",
+                "in": "header"
             }
         },
         "spec": {

test/unit/definitions.spec.ts

@@ -44,6 +44,13 @@ describe('Definition generation', () => {
       expect(expression.evaluate(spec)).to.eq(false);
     });
 
+    it('should generate description for methods and paraemters', () => {
+      let expression = jsonata('paths."/mypath/secondpath".get.parameters[0].description');
+      expect(expression.evaluate(spec)).to.eq('This is the test param description');
+      expression = jsonata('paths."/mypath/secondpath".get.description');
+      expect(expression.evaluate(spec)).to.eq('This is the method description');
+    });
+
     it('should support multiple response decorators', () => {
       let expression = jsonata('paths."/mypath".get.responses."400".description');
       expect(expression.evaluate(spec)).to.eq('The request format was incorrect.');
@@ -276,13 +283,21 @@ describe('Definition generation', () => {
       expression = jsonata('paths."/primitives/{id}".get.parameters[0].format');
       expect(expression.evaluate(spec)).to.eq('int64');
     });
+
+    it('should generate array type names as type + Array', () => {
+      let expression = jsonata('definitions.ResponseBodystringArray');
+      // tslint:disable-next-line:no-unused-expression
+      expect(expression.evaluate(spec)).to.not.be.undefined;
+      expression = jsonata('paths."/primitives/array".get.responses."200".schema."$ref"');
+      expect(expression.evaluate(spec)).to.equal('#/definitions/ResponseBodystringArray');
+    });
   });
 
   describe('ParameterizedEndpoint', () => {
     it('should generate path param for params declared on class', () => {
       const expression = jsonata('paths."/parameterized/{objectId}/test".get.parameters[0].in');
       expect(expression.evaluate(spec)).to.eq('path');
-      });
+    });
   });
 
   describe('AbstractEntityEndpoint', () => {
@@ -296,4 +311,23 @@ describe('Definition generation', () => {
       expect(expression.evaluate(spec)).to.eq('A numeric identifier');
     });
   });
+
+  describe('SecureEndpoint', () => {
+    it('should apply controller security to request', () => {
+      const expression = jsonata('paths."/secure".get.security');
+      expect(expression.evaluate(spec)).to.deep.equal([ { 'access_token': [] } ]);
+    });
+
+    it('method security should override controller security', () => {
+      const expression = jsonata('paths."/secure".post.security');
+      expect(expression.evaluate(spec)).to.deep.equal([ { 'user_email': [] } ]);
+    });
+  });
+
+  describe('SuperSecureEndpoint', () => {
+    it('should apply two controller securities to request', () => {
+      const expression = jsonata('paths."/supersecure".get.security');
+      expect(expression.evaluate(spec)).to.deep.equal([ { 'access_token': [] }, { 'user_email': [] } ]);
+    });
+  });
 });