forked from loopbackio/loopback-next
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(openapi-v3): add OAS3 visibility decorator
closes loopbackio#6392 Signed-off-by: Rifa Achrinza <[email protected]>
- Loading branch information
Showing
7 changed files
with
308 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
122 changes: 122 additions & 0 deletions
122
packages/openapi-v3/src/__tests__/unit/decorators/visibility.decorator.unit.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| // Copyright IBM Corp. 2020. All Rights Reserved. | ||
| // Node module: @loopback/openapi-v3 | ||
| // This file is licensed under the MIT License. | ||
| // License text available at https://opensource.org/licenses/MIT | ||
|
|
||
| import {anOpenApiSpec} from '@loopback/openapi-spec-builder'; | ||
| import {expect} from '@loopback/testlab'; | ||
| import {api, get, getControllerSpec, oas} from '../../..'; | ||
|
|
||
| describe('visibility decorator', () => { | ||
| it('Returns a spec with all the items decorated from the class level', () => { | ||
| const expectedSpec = anOpenApiSpec() | ||
| .withOperationReturningString('get', '/greet', 'greet') | ||
| .withOperationReturningString('get', '/echo', 'echo') | ||
| .build(); | ||
|
|
||
| @api(expectedSpec) | ||
| @oas.visibility('undocumented') | ||
| class MyController { | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
| } | ||
|
|
||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get['x-visibility']).to.eql( | ||
| 'undocumented', | ||
| ); | ||
| expect(actualSpec.paths['/echo'].get['x-visibility']).to.eql( | ||
| 'undocumented', | ||
| ); | ||
| }); | ||
|
|
||
| it('Returns a spec where only one method is undocumented', () => { | ||
| class MyController { | ||
| @get('/greet') | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/echo') | ||
| @oas.visibility('undocumented') | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
| } | ||
|
|
||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get['x-visibility']).to.be.undefined(); | ||
| expect(actualSpec.paths['/echo'].get['x-visibility']).to.eql( | ||
| 'undocumented', | ||
| ); | ||
| }); | ||
|
|
||
| it('Allows a method to override the visibility of a class', () => { | ||
| @oas.visibility('undocumented') | ||
| class MyController { | ||
| @get('/greet') | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/echo') | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/yell') | ||
| @oas.visibility('documented') | ||
| yell() { | ||
| return 'HELLO WORLD!'; | ||
| } | ||
| } | ||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get['x-visibility']).to.eql( | ||
| 'undocumented', | ||
| ); | ||
| expect(actualSpec.paths['/echo'].get['x-visibility']).to.eql( | ||
| 'undocumented', | ||
| ); | ||
| expect(actualSpec.paths['/yell'].get['x-visibility']).to.be.undefined(); | ||
| }); | ||
|
|
||
| it('Allows a class to not be decorated with @oas.visibility at all', () => { | ||
| class MyController { | ||
| @get('/greet') | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/echo') | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
| } | ||
|
|
||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get['x-visibility']).to.be.undefined(); | ||
| expect(actualSpec.paths['/echo'].get['x-visibility']).to.be.undefined(); | ||
| }); | ||
|
|
||
| it('Does not allow a member variable to be decorated', () => { | ||
| const shouldThrow = () => { | ||
| class MyController { | ||
| @oas.visibility('undocumented') | ||
| public foo: string; | ||
|
|
||
| @get('/greet') | ||
| greet() {} | ||
| } | ||
|
|
||
| return getControllerSpec(MyController); | ||
| }; | ||
|
|
||
| expect(shouldThrow).to.throw( | ||
| /^\@oas.visibility cannot be used on a property:/, | ||
| ); | ||
| }); | ||
| }); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
86 changes: 86 additions & 0 deletions
86
packages/openapi-v3/src/decorators/visibility.decorator.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| // Copyright IBM Corp. 2020. All Rights Reserved. | ||
| // Node module: @loopback/openapi-v3 | ||
| // This file is licensed under the MIT License. | ||
| // License text available at https://opensource.org/licenses/MIT | ||
|
|
||
| import { | ||
| ClassDecoratorFactory, | ||
| DecoratorFactory, | ||
| MethodDecoratorFactory, | ||
| } from '@loopback/core'; | ||
| import {OAI3Keys} from '../keys'; | ||
| import {VisibilityDecoratorMetadata} from '../types'; | ||
|
|
||
| const debug = require('debug')( | ||
| 'loopback:openapi3:metadata:controller-spec:visibility', | ||
| ); | ||
|
|
||
| /** | ||
| * Marks an api path with the specfied visibility. When applied to a class, | ||
| * this decorator marks all paths with the specified visibility. | ||
| * | ||
| * You can optionally mark all controllers in a class with | ||
| * `@visibility('undocumented')`, but use `@visibility('documented')` | ||
| * on a specific method to ensure it is not marked as `undocumented`. | ||
| * | ||
| * @param visibilityTyoe - The visbility of the api path on the OAS3 spec. | ||
| * | ||
| * @example | ||
| * ```ts | ||
| * @oas.visibility('undocumented') | ||
| * class MyController { | ||
| * @get('/greet') | ||
| * async function greet() { | ||
| * return 'Hello, World!' | ||
| * } | ||
| * | ||
| * @get('/greet-v2') | ||
| * @oas.deprecated('documented') | ||
| * async function greetV2() { | ||
| * return 'Hello, World!' | ||
| * } | ||
| * } | ||
| * | ||
| * class MyOtherController { | ||
| * @get('/echo') | ||
| * async function echo() { | ||
| * return 'Echo!' | ||
| * } | ||
| * } | ||
| * ``` | ||
| */ | ||
| export function visibility(visibilityType: VisibilityDecoratorMetadata) { | ||
| return function visibilityDecoratorForClassOrMethod( | ||
| // Class or a prototype | ||
| // eslint-disable-next-line @typescript-eslint/no-explicit-any | ||
| target: any, | ||
| method?: string, | ||
| // Use `any` to for `TypedPropertyDescriptor` | ||
| // See https://github.com/strongloop/loopback-next/pull/2704 | ||
| // eslint-disable-next-line @typescript-eslint/no-explicit-any | ||
| methodDescriptor?: TypedPropertyDescriptor<any>, | ||
| ) { | ||
| debug(target, method, methodDescriptor); | ||
|
|
||
| if (method && methodDescriptor) { | ||
| // Method | ||
| return MethodDecoratorFactory.createDecorator< | ||
| VisibilityDecoratorMetadata | ||
| >(OAI3Keys.VISIBILITY_METHOD_KEY, visibilityType, { | ||
| decoratorName: '@oas.visibility', | ||
| })(target, method, methodDescriptor); | ||
| } else if (typeof target === 'function' && !method && !methodDescriptor) { | ||
| // Class | ||
| return ClassDecoratorFactory.createDecorator<VisibilityDecoratorMetadata>( | ||
| OAI3Keys.VISIBILITY_CLASS_KEY, | ||
| visibilityType, | ||
| {decoratorName: '@oas.visibility'}, | ||
| )(target); | ||
| } else { | ||
| throw new Error( | ||
| '@oas.visibility cannot be used on a property: ' + | ||
| DecoratorFactory.getTargetName(target, method, methodDescriptor), | ||
| ); | ||
| } | ||
| }; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters