From 5d12e71b406670c7cdb5744b8521bd441ebcbcf9 Mon Sep 17 00:00:00 2001 From: William Cheng Date: Sun, 23 Nov 2025 16:15:43 +0800 Subject: [PATCH] [typescript-rxjs] Feat: Add @deprecated JSDoc tag to API operations (#22419) * feat(typescript-rxjs): Add @deprecated tag to generated API operations This commit introduces the JSDoc @deprecated tag to API operations in the typescript-rxjs generator when the operation is marked as deprecated in the OpenAPI specification. This ensures that IDEs (like VS Code or WebStorm) correctly flag the method as deprecated, providing better developer experience and warning consumers about upcoming removals or changes. * minor updates --------- Co-authored-by: Dirk Niemeier --- .../resources/typescript-rxjs/apis.mustache | 5 +- .../typescript-rxjs/modelEnum.mustache | 3 + .../typescript-rxjs/modelGeneric.mustache | 9 +++ .../codegen/ruby/RubyClientCodegenTest.java | 56 +++++++++++-------- .../test/resources/3_0/allOf_composition.yaml | 6 +- .../allOf-composition/models/Human.ts | 7 +++ .../builds/default/apis/PetApi.ts | 1 + .../builds/es6-target/apis/PetApi.ts | 1 + .../builds/with-npm-version/apis/PetApi.ts | 1 + .../with-progress-subscriber/apis/PetApi.ts | 1 + 10 files changed, 65 insertions(+), 25 deletions(-) diff --git a/modules/openapi-generator/src/main/resources/typescript-rxjs/apis.mustache b/modules/openapi-generator/src/main/resources/typescript-rxjs/apis.mustache index e0ca79a7946f..640a4a8b6410 100644 --- a/modules/openapi-generator/src/main/resources/typescript-rxjs/apis.mustache +++ b/modules/openapi-generator/src/main/resources/typescript-rxjs/apis.mustache @@ -39,6 +39,9 @@ export class {{classname}} extends BaseAPI { {{#summary}} * {{&summary}} {{/summary}} + {{#isDeprecated}} + * @deprecated + {{/isDeprecated}} */ {{nickname}}({{#allParams.0}}{ {{#allParams}}{{paramName}}{{#vendorExtensions.x-param-name-alternative}}: {{vendorExtensions.x-param-name-alternative}}{{/vendorExtensions.x-param-name-alternative}}{{^-last}}, {{/-last}}{{/allParams}} }: {{operationIdCamelCase}}Request{{/allParams.0}}): Observable<{{{returnType}}}{{^returnType}}void{{/returnType}}> {{#withProgressSubscriber}} @@ -244,4 +247,4 @@ export enum {{operationIdCamelCase}}{{enumName}} { {{/allParams}} {{/operation}} {{/operations}} -{{/hasEnums}} +{{/hasEnums}} \ No newline at end of file diff --git a/modules/openapi-generator/src/main/resources/typescript-rxjs/modelEnum.mustache b/modules/openapi-generator/src/main/resources/typescript-rxjs/modelEnum.mustache index dc04cb0bd63d..3516dcd60387 100644 --- a/modules/openapi-generator/src/main/resources/typescript-rxjs/modelEnum.mustache +++ b/modules/openapi-generator/src/main/resources/typescript-rxjs/modelEnum.mustache @@ -2,6 +2,9 @@ * {{{description}}} * @export * @enum {string} +{{#deprecated}} + * @deprecated +{{/deprecated}} */ export enum {{classname}} { {{#allowableValues}} diff --git a/modules/openapi-generator/src/main/resources/typescript-rxjs/modelGeneric.mustache b/modules/openapi-generator/src/main/resources/typescript-rxjs/modelGeneric.mustache index a12ceb35c3dc..854d4de53c9a 100644 --- a/modules/openapi-generator/src/main/resources/typescript-rxjs/modelGeneric.mustache +++ b/modules/openapi-generator/src/main/resources/typescript-rxjs/modelGeneric.mustache @@ -10,6 +10,9 @@ import type { * {{{.}}}{{/description}} * @export * @interface {{classname}} +{{#deprecated}} + * @deprecated +{{/deprecated}} */ export interface {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{ {{#additionalPropertiesType}} @@ -18,6 +21,9 @@ export interface {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{ {{#vars}} /**{{#description}} * {{{.}}}{{/description}} + {{#deprecated}} + * @deprecated + {{/deprecated}} * @type {{=<% %>=}}{<%&datatype%>}<%={{ }}=%> * @memberof {{classname}} */ @@ -30,6 +36,9 @@ export interface {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{ /** * @export * @enum {string} +{{#deprecated}} + * @deprecated +{{/deprecated}} */ export enum {{classname}}{{enumName}} { {{#allowableValues}} diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/ruby/RubyClientCodegenTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/ruby/RubyClientCodegenTest.java index dc1db42fae02..68c2254e5a69 100644 --- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/ruby/RubyClientCodegenTest.java +++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/ruby/RubyClientCodegenTest.java @@ -564,8 +564,8 @@ public class RubyClientCodegenTest { Assert.assertNotNull(superMan); // to test all properties - Assert.assertEquals(superMan.getVars().size(), 6); - Assert.assertEquals(superMan.getAllVars().size(), 6); + Assert.assertEquals(superMan.getVars().size(), 7); + Assert.assertEquals(superMan.getAllVars().size(), 7); Assert.assertEquals(superMan.getMandatory().size(), 3); Assert.assertEquals(superMan.getAllMandatory().size(), 3); @@ -578,45 +578,55 @@ public class RubyClientCodegenTest { Assert.assertFalse(cp1.required); CodegenProperty cp2 = superMan.getVars().get(2); - Assert.assertEquals(cp2.name, "reward"); + Assert.assertEquals(cp2.name, "nickname"); Assert.assertFalse(cp2.required); + Assert.assertTrue(cp2.deprecated); CodegenProperty cp3 = superMan.getVars().get(3); - Assert.assertEquals(cp3.name, "origin"); - Assert.assertTrue(cp3.required); + Assert.assertEquals(cp3.name, "reward"); + Assert.assertFalse(cp3.required); CodegenProperty cp4 = superMan.getVars().get(4); - Assert.assertEquals(cp4.name, "category"); - Assert.assertFalse(cp4.required); + Assert.assertEquals(cp4.name, "origin"); + Assert.assertTrue(cp4.required); CodegenProperty cp5 = superMan.getVars().get(5); - Assert.assertEquals(cp5.name, "level"); - Assert.assertTrue(cp5.required); + Assert.assertEquals(cp5.name, "category"); + Assert.assertFalse(cp5.required); - CodegenProperty cp6 = superMan.getAllVars().get(0); - Assert.assertEquals(cp6.name, "id"); + CodegenProperty cp6 = superMan.getVars().get(6); + Assert.assertEquals(cp6.name, "level"); Assert.assertTrue(cp6.required); - CodegenProperty cp7 = superMan.getAllVars().get(1); - Assert.assertEquals(cp7.name, "name"); - Assert.assertFalse(cp7.required); + CodegenProperty cp7 = superMan.getAllVars().get(0); + Assert.assertEquals(cp7.name, "id"); + Assert.assertTrue(cp7.required); - CodegenProperty cp8 = superMan.getAllVars().get(2); - Assert.assertEquals(cp8.name, "reward"); + CodegenProperty cp8 = superMan.getAllVars().get(1); + Assert.assertEquals(cp8.name, "name"); Assert.assertFalse(cp8.required); - CodegenProperty cp9 = superMan.getAllVars().get(3); - Assert.assertEquals(cp9.name, "origin"); - Assert.assertTrue(cp9.required); + CodegenProperty cp9 = superMan.getAllVars().get(2); + Assert.assertEquals(cp9.name, "nickname"); + Assert.assertFalse(cp9.required); + Assert.assertTrue(cp9.deprecated); - CodegenProperty cp10 = superMan.getAllVars().get(4); - Assert.assertEquals(cp10.name, "category"); + CodegenProperty cp10 = superMan.getAllVars().get(3); + Assert.assertEquals(cp10.name, "reward"); Assert.assertFalse(cp10.required); - CodegenProperty cp11 = superMan.getAllVars().get(5); - Assert.assertEquals(cp11.name, "level"); + CodegenProperty cp11 = superMan.getAllVars().get(4); + Assert.assertEquals(cp11.name, "origin"); Assert.assertTrue(cp11.required); + CodegenProperty cp12 = superMan.getAllVars().get(5); + Assert.assertEquals(cp12.name, "category"); + Assert.assertFalse(cp12.required); + + CodegenProperty cp13 = superMan.getAllVars().get(6); + Assert.assertEquals(cp13.name, "level"); + Assert.assertTrue(cp13.required); + } diff --git a/modules/openapi-generator/src/test/resources/3_0/allOf_composition.yaml b/modules/openapi-generator/src/test/resources/3_0/allOf_composition.yaml index 3b2c6a1be5d6..75205af519e3 100644 --- a/modules/openapi-generator/src/test/resources/3_0/allOf_composition.yaml +++ b/modules/openapi-generator/src/test/resources/3_0/allOf_composition.yaml @@ -81,4 +81,8 @@ components: format: int64 name: type: string - example: Tom + example: Tom + nickname: + type: string + description: Previous short name for the human, replaced by `name` + deprecated: true diff --git a/samples/client/others/typescript-rxjs/allOf-composition/models/Human.ts b/samples/client/others/typescript-rxjs/allOf-composition/models/Human.ts index 2122f4c7a134..9cf274075e8e 100644 --- a/samples/client/others/typescript-rxjs/allOf-composition/models/Human.ts +++ b/samples/client/others/typescript-rxjs/allOf-composition/models/Human.ts @@ -27,4 +27,11 @@ export interface Human { * @memberof Human */ name?: string; + /** + * Previous short name for the human, replaced by `name` + * @deprecated + * @type {string} + * @memberof Human + */ + nickname?: string; } diff --git a/samples/client/petstore/typescript-rxjs/builds/default/apis/PetApi.ts b/samples/client/petstore/typescript-rxjs/builds/default/apis/PetApi.ts index 7745f081c8bb..5629cf25de2c 100644 --- a/samples/client/petstore/typescript-rxjs/builds/default/apis/PetApi.ts +++ b/samples/client/petstore/typescript-rxjs/builds/default/apis/PetApi.ts @@ -149,6 +149,7 @@ export class PetApi extends BaseAPI { /** * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. * Finds Pets by tags + * @deprecated */ findPetsByTags({ tags }: FindPetsByTagsRequest): Observable> findPetsByTags({ tags }: FindPetsByTagsRequest, opts?: OperationOpts): Observable>> diff --git a/samples/client/petstore/typescript-rxjs/builds/es6-target/apis/PetApi.ts b/samples/client/petstore/typescript-rxjs/builds/es6-target/apis/PetApi.ts index 7745f081c8bb..5629cf25de2c 100644 --- a/samples/client/petstore/typescript-rxjs/builds/es6-target/apis/PetApi.ts +++ b/samples/client/petstore/typescript-rxjs/builds/es6-target/apis/PetApi.ts @@ -149,6 +149,7 @@ export class PetApi extends BaseAPI { /** * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. * Finds Pets by tags + * @deprecated */ findPetsByTags({ tags }: FindPetsByTagsRequest): Observable> findPetsByTags({ tags }: FindPetsByTagsRequest, opts?: OperationOpts): Observable>> diff --git a/samples/client/petstore/typescript-rxjs/builds/with-npm-version/apis/PetApi.ts b/samples/client/petstore/typescript-rxjs/builds/with-npm-version/apis/PetApi.ts index 7745f081c8bb..5629cf25de2c 100644 --- a/samples/client/petstore/typescript-rxjs/builds/with-npm-version/apis/PetApi.ts +++ b/samples/client/petstore/typescript-rxjs/builds/with-npm-version/apis/PetApi.ts @@ -149,6 +149,7 @@ export class PetApi extends BaseAPI { /** * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. * Finds Pets by tags + * @deprecated */ findPetsByTags({ tags }: FindPetsByTagsRequest): Observable> findPetsByTags({ tags }: FindPetsByTagsRequest, opts?: OperationOpts): Observable>> diff --git a/samples/client/petstore/typescript-rxjs/builds/with-progress-subscriber/apis/PetApi.ts b/samples/client/petstore/typescript-rxjs/builds/with-progress-subscriber/apis/PetApi.ts index 1fd55eca4bcf..2313c4beb053 100644 --- a/samples/client/petstore/typescript-rxjs/builds/with-progress-subscriber/apis/PetApi.ts +++ b/samples/client/petstore/typescript-rxjs/builds/with-progress-subscriber/apis/PetApi.ts @@ -155,6 +155,7 @@ export class PetApi extends BaseAPI { /** * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. * Finds Pets by tags + * @deprecated */ findPetsByTags({ tags }: FindPetsByTagsRequest): Observable> findPetsByTags({ tags }: FindPetsByTagsRequest, opts?: Pick): Observable>