Merge pull request lukeautry#498 from ryankeener/hidden-controller

Add support for using @hidden() decorator on controllers

Author: dgreene1

README.MD

@@ -800,6 +800,35 @@ public async find(): Promise<any> {
 }
 ```
 
+### Hidden
+
+Excludes this endpoint from the generated swagger document.
+
+```ts
+  @Get()
+  @Hidden()
+  public async find(): Promise<any> {
+
+  }
+```
+
+It can also be set at the controller level to exclude all of its endpoints from the swagger document.
+
+```ts
+@Hidden()
+export class HiddenController {
+  @Get()
+  public async find(): Promise<any> {
+
+  }
+
+  @Post()
+  public async create(): Promise<any> {
+
+  }
+}
+```
+
 ## Command Line Interface
 
 For information on the configuration object (tsoa.json), check out the following:

src/metadataGeneration/controllerGenerator.ts

@@ -10,11 +10,13 @@ export class ControllerGenerator {
   private readonly path?: string;
   private readonly tags?: string[];
   private readonly security?: Tsoa.Security[];
+  private readonly isHidden?: boolean;
 
   constructor(private readonly node: ts.ClassDeclaration, private readonly current: MetadataGenerator) {
     this.path = this.getPath();
     this.tags = this.getTags();
     this.security = this.getSecurity();
+    this.isHidden = this.getIsHidden();
   }
 
   public IsValid() {
@@ -42,7 +44,7 @@ export class ControllerGenerator {
   private buildMethods() {
     return this.node.members
       .filter(m => m.kind === ts.SyntaxKind.MethodDeclaration)
-      .map((m: ts.MethodDeclaration) => new MethodGenerator(m, this.current, this.tags, this.security))
+      .map((m: ts.MethodDeclaration) => new MethodGenerator(m, this.current, this.tags, this.security, this.isHidden))
       .filter(generator => generator.IsValid())
       .map(generator => generator.Generate());
   }
@@ -85,4 +87,16 @@ export class ControllerGenerator {
 
     return getSecurities(securityDecorators);
   }
+
+  private getIsHidden(): boolean {
+    const hiddenDecorators = getDecorators(this.node, identifier => identifier.text === 'Hidden');
+    if (!hiddenDecorators || !hiddenDecorators.length) {
+      return false;
+    }
+    if (hiddenDecorators.length > 1) {
+      throw new GenerateMetadataError(`Only one Hidden decorator allowed in '${this.node.name!.text}' class.`);
+    }
+
+    return true;
+  }
 }

src/metadataGeneration/methodGenerator.ts

@@ -13,7 +13,13 @@ export class MethodGenerator {
   private method: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head';
   private path: string;
 
-  constructor(private readonly node: ts.MethodDeclaration, private readonly current: MetadataGenerator, private readonly parentTags?: string[], private readonly parentSecurity?: Tsoa.Security[]) {
+  constructor(
+    private readonly node: ts.MethodDeclaration,
+    private readonly current: MetadataGenerator,
+    private readonly parentTags?: string[],
+    private readonly parentSecurity?: Tsoa.Security[],
+    private readonly isParentHidden?: boolean,
+  ) {
     this.processMethodDecorators();
   }
 
@@ -251,8 +257,13 @@ export class MethodGenerator {
   private getIsHidden() {
     const hiddenDecorators = this.getDecoratorsByIdentifier(this.node, 'Hidden');
     if (!hiddenDecorators || !hiddenDecorators.length) {
-      return false;
+      return !!this.isParentHidden;
+    }
+
+    if (this.isParentHidden) {
+      throw new GenerateMetadataError(`Hidden decorator cannot be set on '${this.getCurrentLocation()}' it is already defined on the controller`);
     }
+
     if (hiddenDecorators.length > 1) {
       throw new GenerateMetadataError(`Only one Hidden decorator allowed in '${this.getCurrentLocation}' method.`);
     }

tests/fixtures/controllers/hiddenController.ts

@@ -0,0 +1,16 @@
+import { Controller, Get, Hidden, Post, Route } from '../../../src';
+import { ModelService } from '../services/modelService';
+import { TestModel } from '../testModel';
+
+@Route('Controller')
+@Hidden()
+export class HiddenMethodController extends Controller {
+  @Get('hiddenGetMethod')
+  public async hiddenGetMethod(): Promise<TestModel> {
+    return Promise.resolve(new ModelService().getModel());
+  }
+  @Post('hiddenPostMethod')
+  public async hiddenPostMethod(): Promise<TestModel> {
+    return Promise.resolve(new ModelService().getModel());
+  }
+}

tests/unit/swagger/definitionsGeneration/metadata.spec.ts

@@ -480,7 +480,7 @@ describe('Metadata generation', () => {
     const parameterMetadata = new MetadataGenerator('./tests/fixtures/controllers/hiddenMethodController.ts').Generate();
     const controller = parameterMetadata.controllers[0];
 
-    it('should generate methods visible by default', () => {
+    it('should mark methods as visible by default', () => {
       const method = controller.methods.find(m => m.name === 'normalGetMethod');
       if (!method) {
         throw new Error('Method normalGetMethod not defined!');
@@ -491,7 +491,7 @@ describe('Metadata generation', () => {
       expect(method.isHidden).to.equal(false);
     });
 
-    it('should generate hidden methods', () => {
+    it('should mark methods as hidden', () => {
       const method = controller.methods.find(m => m.name === 'hiddenGetMethod');
       if (!method) {
         throw new Error('Method hiddenGetMethod not defined!');
@@ -503,6 +503,18 @@ describe('Metadata generation', () => {
     });
   });
 
+  describe('HiddenControllerGenerator', () => {
+    const parameterMetadata = new MetadataGenerator('./tests/fixtures/controllers/hiddenController.ts').Generate();
+    const controller = parameterMetadata.controllers[0];
+
+    it('should mark all methods as hidden', () => {
+      expect(controller.methods).to.have.lengthOf(2);
+      controller.methods.forEach(method => {
+        expect(method.isHidden).to.equal(true);
+      });
+    });
+  });
+
   describe('DeprecatedMethodGenerator', () => {
     const parameterMetadata = new MetadataGenerator('./tests/fixtures/controllers/deprecatedController.ts').Generate();
     const controller = parameterMetadata.controllers[0];

tests/unit/swagger/schemaDetails.spec.ts

@@ -1,5 +1,7 @@
-import { expect } from 'chai';
 import 'mocha';
+
+import { expect } from 'chai';
+
 import { MetadataGenerator } from '../../../src/metadataGeneration/metadataGenerator';
 import { SpecGenerator2 } from '../../../src/swagger/specGenerator2';
 import { getDefaultOptions } from '../../fixtures/defaultOptions';
@@ -52,4 +54,22 @@ describe('Schema details generation', () => {
   }
 
   it('should set API license if provided', () => expect(licenseName).to.equal(getDefaultOptions().license));
+
+  describe('paths', () => {
+    describe('hidden paths', () => {
+      it('should not contain hidden paths', () => {
+        const metadataHiddenMethod = new MetadataGenerator('./tests/fixtures/controllers/hiddenMethodController.ts').Generate();
+        const specHiddenMethod = new SpecGenerator2(metadataHiddenMethod, getDefaultOptions()).GetSpec();
+
+        expect(specHiddenMethod.paths).to.have.keys(['/Controller/normalGetMethod']);
+      });
+
+      it('should not contain paths for hidden controller', () => {
+        const metadataHiddenController = new MetadataGenerator('./tests/fixtures/controllers/hiddenController.ts').Generate();
+        const specHiddenController = new SpecGenerator2(metadataHiddenController, getDefaultOptions()).GetSpec();
+
+        expect(specHiddenController.paths).to.be.empty;
+      });
+    });
+  });
 });

tests/unit/swagger/schemaDetails3.spec.ts

@@ -130,6 +130,21 @@ describe('Definition generation for OpenAPI 3.0.0', () => {
         });
       });
     });
+    describe('hidden paths', () => {
+      it('should not contain hidden paths', () => {
+        const metadataHiddenMethod = new MetadataGenerator('./tests/fixtures/controllers/hiddenMethodController.ts').Generate();
+        const specHiddenMethod = new SpecGenerator3(metadataHiddenMethod, getDefaultOptions()).GetSpec();
+
+        expect(specHiddenMethod.paths).to.have.keys(['/Controller/normalGetMethod']);
+      });
+
+      it('should not contain paths for hidden controller', () => {
+        const metadataHiddenController = new MetadataGenerator('./tests/fixtures/controllers/hiddenController.ts').Generate();
+        const specHiddenController = new SpecGenerator3(metadataHiddenController, getDefaultOptions()).GetSpec();
+
+        expect(specHiddenController.paths).to.be.empty;
+      });
+    });
   });
 
   describe('components', () => {