feat: enhance EnumTransformer and SpecGenerator to support title property, with corresponding tests

Author: WoH

packages/cli/src/metadataGeneration/transformer/enumTransformer.ts

@@ -28,6 +28,7 @@ export class EnumTransformer extends Transformer {
     const enumVarnames = first.enumVarnames ? (second.enumVarnames ? [...first.enumVarnames, ...second.enumVarnames] : first.enumVarnames) : second.enumVarnames;
 
     const example = first.example || second.example;
+    const title = first.title || second.title;
 
     return {
       dataType: 'refEnum',
@@ -37,6 +38,7 @@ export class EnumTransformer extends Transformer {
       refName: first.refName,
       deprecated,
       example,
+      ...(title && { title }),
     };
   }
 
@@ -57,6 +59,7 @@ export class EnumTransformer extends Transformer {
     };
     const enums = declaration.members.map(e => resolver.current.typeChecker.getConstantValue(e)).filter(isNotUndefined);
     const enumVarnames = declaration.members.map(e => e.name.getText()).filter(isNotUndefined);
+    const title = resolver.getNodeTitle(declaration);
 
     return {
       dataType: 'refEnum',
@@ -66,6 +69,7 @@ export class EnumTransformer extends Transformer {
       enumVarnames,
       refName: enumName,
       deprecated: isExistJSDocTag(declaration, tag => tag.tagName.text === 'deprecated'),
+      ...(title && { title }),
     };
   }
 

packages/cli/src/swagger/specGenerator2.ts

@@ -424,6 +424,10 @@ export class SpecGenerator2 extends SpecGenerator {
         swaggerType['x-deprecated'] = true;
       }
 
+      if (property.title) {
+        swaggerType.title = property.title;
+      }
+
       if (property.extensions) {
         property.extensions.forEach(property => {
           swaggerType[property.key] = property.value;

packages/cli/src/swagger/specGenerator3.ts

@@ -588,6 +588,10 @@ export class SpecGenerator3 extends SpecGenerator {
         swaggerType.deprecated = true;
       }
 
+      if (property.title) {
+        swaggerType.title = property.title;
+      }
+
       if (property.extensions) {
         property.extensions.forEach(property => {
           swaggerType[property.key] = property.value;

tests/fixtures/testModel.ts

@@ -182,6 +182,7 @@ export interface TestModel extends Model {
   // prettier-ignore
   stringAndBoolArray?: Array<(string | boolean)>;
   testModelWithAnnotations?: TestModelWithAnnotations;
+  enumWithTitle?: EnumWithTitle;
 
   /**
    * @example {
@@ -1306,3 +1307,11 @@ interface TestModelWithAnnotations {
    */
   param: string;
 }
+
+/**
+ * @title Title annotation for enum
+ */
+export enum EnumWithTitle {
+  Value1 = 'value1',
+  Value2 = 'value2',
+}

tests/unit/metadataGeneration/transformer/enumTransformer.spec.ts

@@ -207,6 +207,57 @@ describe('EnumTransformer - Null Safety', () => {
         example: 'example1', // First example should be used
       });
     });
+
+    it('should merge title property correctly', () => {
+      const first: Tsoa.RefEnumType = {
+        dataType: 'refEnum',
+        refName: 'TestEnum',
+        enums: ['value1'],
+        enumVarnames: ['VALUE1'],
+        description: 'First enum',
+        deprecated: false,
+        title: 'First Title',
+      };
+
+      const second: Tsoa.RefEnumType = {
+        dataType: 'refEnum',
+        refName: 'TestEnum',
+        enums: ['value2'],
+        enumVarnames: ['VALUE2'],
+        description: 'Second enum',
+        deprecated: false,
+        title: 'Second Title',
+      };
+
+      const result = EnumTransformer.merge(first, second);
+
+      expect(result.title).to.equal('First Title'); // First title should be used
+    });
+
+    it('should use second title if first is undefined', () => {
+      const first: Tsoa.RefEnumType = {
+        dataType: 'refEnum',
+        refName: 'TestEnum',
+        enums: ['value1'],
+        enumVarnames: ['VALUE1'],
+        description: 'First enum',
+        deprecated: false,
+      };
+
+      const second: Tsoa.RefEnumType = {
+        dataType: 'refEnum',
+        refName: 'TestEnum',
+        enums: ['value2'],
+        enumVarnames: ['VALUE2'],
+        description: 'Second enum',
+        deprecated: false,
+        title: 'Second Title',
+      };
+
+      const result = EnumTransformer.merge(first, second);
+
+      expect(result.title).to.equal('Second Title');
+    });
   });
 
   describe('mergeMany method', () => {

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

@@ -1632,6 +1632,12 @@ describe('Definition generation', () => {
           testModelWithAnnotations: () => {
             // schema is validated in OpenAPI 3 specific tests
           },
+          enumWithTitle: (propertyName, propertySchema) => {
+            expect(propertySchema.$ref).to.eq('#/definitions/EnumWithTitle', `for property ${propertyName}.$ref`);
+
+            const schema = getValidatedDefinition('EnumWithTitle', currentSpec);
+            expect(schema.title).to.eq('Title annotation for enum');
+          },
           extensionComment: (propertyName, propertySchema) => {
             expect(propertySchema).to.deep.eq(
               {

tests/unit/swagger/schemaDetails3.spec.ts

@@ -2000,6 +2000,12 @@ describe('Definition generation for OpenAPI 3.0.0', () => {
 
             expect(paramSchema.title).to.eq('Title annotation for property');
           },
+          enumWithTitle: (propertyName, propertySchema) => {
+            expect(propertySchema.$ref).to.eq('#/components/schemas/EnumWithTitle', `for property ${propertyName}.$ref`);
+
+            const schema = getComponentSchema('EnumWithTitle', currentSpec);
+            expect(schema.title).to.eq('Title annotation for enum');
+          },
           advancedTypeAliases: (propertyName, propertySchema) => {
             expect(propertySchema).to.deep.eq(
               {

tests/unit/swagger/schemaDetails31.spec.ts

@@ -4500,6 +4500,12 @@ describe('Definition generation for OpenAPI 3.1.0', () => {
 
             expect(paramSchema.title).to.eq('Title annotation for property');
           },
+          enumWithTitle: (propertyName, propertySchema) => {
+            expect(propertySchema.$ref).to.eq('#/components/schemas/EnumWithTitle', `for property ${propertyName}.$ref`);
+
+            const schema = getComponentSchema('EnumWithTitle', currentSpec);
+            expect(schema.title).to.eq('Title annotation for enum');
+          },
         };
 
         const testModel = currentSpec.spec.components.schemas[interfaceModelName];