Allow marking @Headers params as optional without CLI Plugin

[farshidbeheshti]

Is your feature request related to a problem? Please describe it

Yes. Currently, when using the @Headers('x-key') parameter decorator in a controller without the CLI Plugin enabled, the generated Swagger documentation marks the header as Required, even if the TypeScript parameter is marked as optional (?).

@Get()
// Without CLI Plugin: Generates "required: true" in Swagger UI
get(@Headers('x-signature') signature?: string) {} 

While enabling the CLI Plugin fixes this via AST introspection, relying on a build-time plugin just to get correct optionality for headers feels like a heavy requirement. Developers who don't use the CLI plugin (or can't for some reason) are left with incorrect documentation or clunky workarounds (manually extracting headers from @Req() just to use @ApiHeader({ required: false }) on the method).

Describe the solution you'd like

I would like a way to explicitly control the optionality of a header parameter via decorators, so it works correctly at runtime without the CLI plugin.

Potential Solutions:
1- Support @ApiHeader (or similar) on the parameter level:
get(@ApiHeader({ required: false }) @Headers('x-sig') sig: string) {}

2- Support @optional() from common:
If @Optional() is present, default to required: false

3- Support options in @headers (Core Change?):
@Headers('x-sig', { optional: true }) (This might be out of scope for the swagger module alone)

Teachability, documentation, adoption, migration strategy

This is a non-breaking DX improvement.

• Adoption: Immediate for users struggling with header documentation.
• Docs: Update documentation to mention that for non-CLI users, they can use the new decorator/flag to ensure optional headers are documented correctly

What is the motivation / use case for changing the behavior?

DX.
The current behavior violates the principle of least surprise ("I typed it as optional, why does the doc say required?"). Forcing the adoption of the CLI plugin, which changes build processes, just to fix a header definition seems disproportionate. A declarative runtime solution would be much cleaner.

[farshidbeheshti]

This has been a known confusion point. For example, see this Stack Overflow discussion where users struggle to make headers optional without duplicating them or restructuring their code:
https://stackoverflow.com/questions/75466234/optional-headers-on-swagger-typescript

The answer there does not actually resolve the issue