feat: add node decorator processor system for dynamic OpenAPI schema

[m2broth]

📋 Overview

This PR introduces a new option in metadata generator that allows custom decorators to dynamically extend OpenAPI schemas during the tsoa code generation process. This enables third-party services, middleware, and custom business logic to inject metadata directly into the generated OpenAPI specifications.

✨ Key Features

• Custom Decorator Processing: Register custom decorators that can modify OpenAPI method metadata
• Type-Safe Implementation: Full TypeScript support with proper type checking
• Flexible Configuration: Easy integration through MetadataGeneratorOptions
• Extensible Architecture: Clean separation of concerns with processor interfaces

🔧 Implementation Details

Core Components

1. NodeDecoratorProcessor Interface

   export type NodeDecoratorProcessor = (context: DecoratorProcessorContext) => void;
   
   export interface DecoratorProcessorContext {
     methodObject: Tsoa.Method;
     decoratorArguments: any[];
   }

2. MetadataGenerator Integration

   • Added customDecoratorProcessors to MetadataGeneratorOptions
   • Processors are executed during method metadata generation
   • Full error handling and validation

3. MethodGenerator Enhancement

   • New processCustomDecorators method
   • Automatic decorator detection and processing
   • Context injection for processor execution

Usage

1. Create Your Decorator & Processor

// myCustomDecorator.ts
import { NodeDecoratorProcessor } from '@namecheap/tsoa-cli';

export function MyCustomDecorator(value: string): MethodDecorator {
  return (target, propertyKey, descriptor) => descriptor;
}

export const MyCustomProcessor: NodeDecoratorProcessor = ({ methodObject, decoratorArguments }) => {
  if (!methodObject.extensions) methodObject.extensions = [];
  
  methodObject.extensions.push({
    key: 'x-my-custom-extension',
    value: { customValue: decoratorArguments[0] }
  });
};

2. Register in Your Service

// your-service.ts
import { MetadataGenerator } from '@namecheap/tsoa-cli';
import { MyCustomProcessor } from './myCustomDecorator';

const metadata = new MetadataGenerator(
  'src/controllers/**/*.ts',
  {},
  [],
  undefined,
  {
    customDecoratorProcessors: {
      'MyCustomDecorator': MyCustomProcessor
    }
  }
);

3. Use in Controllers

// userController.ts
import { Route, Get, Controller } from '@namecheap/tsoa-runtime';
import { MyCustomDecorator } from './myCustomDecorator';

@Route('api')
export class UserController extends Controller {
  @Get('users')
  @MyCustomDecorator('custom-value')
  public async getUsers(): Promise<User[]> {
    return this.userService.getUsers();
  }
}

4. Generated OpenAPI Output

paths:
  /api/users:
    get:
      x-my-custom-extension:
        customValue: "custom-value"

[b1ff]

@wRLSS @m2broth it looks like we need to add github actions here

[m2broth]

@wRLSS @m2broth it looks like we need to add github actions here

@wRLSS Could you check Settings -> Actions -> General and Settings -> Branches for brunch protection rules and workflows are enabled for this repository

[m2broth]

@wRLSS @m2broth it looks like we need to add github actions here

I've resolved running gh actions in the repository and fixed running tests

[b1ff]

when this error is thrown it would be hard to debug given that original one is going to be missign

[m2broth]

current GenerateMetadataError class isn't supposed to work with original Error object. I added node object as a second GenerateMetadataError constructor argument

[b1ff]

does it mean that consumers must be adding separate decorators for documentation?

[m2broth]

No, this is just as example. The device gets current decorators by provided name and then applies any modification to the openapi method metadata