-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: adds @oas.deprecated() decorator
- Loading branch information
1 parent
d9f5741
commit 6b6b5f0
Showing
6 changed files
with
297 additions
and
2 deletions.
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
112 changes: 112 additions & 0 deletions
112
packages/openapi-v3/src/__tests__/unit/decorators/deprecated.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,112 @@ | ||
| // Copyright IBM Corp. 2019. 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('deprecation 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.deprecated() | ||
| class MyController { | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
| } | ||
|
|
||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get.deprecated).to.eql(true); | ||
| expect(actualSpec.paths['/echo'].get.deprecated).to.eql(true); | ||
| }); | ||
|
|
||
| it('Returns a spec where only one method is deprecated', () => { | ||
| class MyController { | ||
| @get('/greet') | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/echo') | ||
| @oas.deprecated() | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
| } | ||
|
|
||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get.deprecated).to.be.undefined(); | ||
| expect(actualSpec.paths['/echo'].get.deprecated).to.eql(true); | ||
| }); | ||
|
|
||
| it('Allows a method to override the deprecation of a class', () => { | ||
| @oas.deprecated() | ||
| class MyController { | ||
| @get('/greet') | ||
| greet() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/echo') | ||
| echo() { | ||
| return 'Hello world!'; | ||
| } | ||
|
|
||
| @get('/yell') | ||
| @oas.deprecated(false) | ||
| yell() { | ||
| return 'HELLO WORLD!'; | ||
| } | ||
| } | ||
| const actualSpec = getControllerSpec(MyController); | ||
| expect(actualSpec.paths['/greet'].get.deprecated).to.eql(true); | ||
| expect(actualSpec.paths['/echo'].get.deprecated).to.eql(true); | ||
| expect(actualSpec.paths['/yell'].get.deprecated).to.be.undefined(); | ||
| }); | ||
|
|
||
| it('Allows a class to not be decorated with @oas.deprecated 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.deprecated).to.be.undefined(); | ||
| expect(actualSpec.paths['/echo'].get.deprecated).to.be.undefined(); | ||
| }); | ||
|
|
||
| it('Does not allow a member variable to be decorated', () => { | ||
| const shouldThrow = () => { | ||
| class MyController { | ||
| @oas.deprecated() | ||
| public foo: string; | ||
|
|
||
| @get('/greet') | ||
| greet() {} | ||
| } | ||
|
|
||
| return getControllerSpec(MyController); | ||
| }; | ||
|
|
||
| expect(shouldThrow).to.throw( | ||
| /^\@oas.deprecated 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
87 changes: 87 additions & 0 deletions
87
packages/openapi-v3/src/decorators/deprecated.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,87 @@ | ||
| // Copyright IBM Corp. 2018. 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'; | ||
|
|
||
| const debug = require('debug')( | ||
| 'loopback:openapi3:metadata:controller-spec:deprecated', | ||
| ); | ||
|
|
||
| /** | ||
| * Marks an api path as deprecated. When applied to a class, this decorator | ||
| * marks all paths as deprecated. | ||
| * | ||
| * You can optionally mark all controllers in a class as deprecated, but use | ||
| * `@deprecated(false)` on a specific method to ensure it is not marked | ||
| * as deprecated in the specification. | ||
| * | ||
| * @param isDeprecated - whether or not the path should be marked as deprecated. | ||
| * This is useful for marking a class as deprecated, but a method as | ||
| * not deprecated. | ||
| * | ||
| * @example | ||
| * ```ts | ||
| * @oas.deprecated() | ||
| * class MyController { | ||
| * @get('/greet') | ||
| * public async function greet() { | ||
| * return 'Hello, World!' | ||
| * } | ||
| * | ||
| * @get('/greet-v2') | ||
| * @oas.deprecated(false) | ||
| * public async function greetV2() { | ||
| * return 'Hello, World!' | ||
| * } | ||
| * } | ||
| * | ||
| * class MyOtherController { | ||
| * @get('/echo') | ||
| * public async function echo() { | ||
| * return 'Echo!' | ||
| * } | ||
| * } | ||
| * ``` | ||
| */ | ||
| export function deprecated(isDeprecated = true) { | ||
| return function deprecatedDecoratorForClassOrMethod( | ||
| // 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<boolean>( | ||
| OAI3Keys.DEPRECATED_METHOD_KEY, | ||
| isDeprecated, | ||
| {decoratorName: '@oas.deprecated'}, | ||
| )(target, method, methodDescriptor); | ||
| } else if (typeof target === 'function' && !method && !methodDescriptor) { | ||
| // Class | ||
| return ClassDecoratorFactory.createDecorator<boolean>( | ||
| OAI3Keys.DEPRECATED_CLASS_KEY, | ||
| isDeprecated, | ||
| {decoratorName: '@oas.deprecated'}, | ||
| )(target); | ||
| } else { | ||
| throw new Error( | ||
| '@oas.deprecated 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