Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Bundle repeated Swagger header/response decorators into a named composite via applyDecorators()
Collapse a repeated stack of @ApiHeader/@ApiResponse decorators into one reusable applyDecorators() decorator instead of copy-pasting it on every endpoint.
Bad example
| 1 | @Get() |
| 2 | @ApiHeader({ name: 'x-api-key', description: 'HMAC API key', required: false }) |
| 3 | @ApiHeader({ name: 'token', description: 'MWS authorization token', required: false }) |
| 4 | @ApiHeader({ name: 'x-auth-token', description: 'Authorization token', required: false }) |
| 5 | getA() {} |
| 6 |
|
| 7 | @Post() |
| 8 | @ApiHeader({ name: 'x-api-key', description: 'HMAC API key', required: false }) |
| 9 | @ApiHeader({ name: 'token', description: 'MWS authorization token', required: false }) |
| 10 | @ApiHeader({ name: 'x-auth-token', description: 'Authorization token', required: false }) |
| 11 | postB() {} |
Explanation (EN)
The same three auth headers are duplicated on every endpoint. Adding or renaming a header means editing every handler, and the docs drift the moment one is missed.
Objašnjenje (HR)
Ista tri auth headera dupliciraju se na svakom endpointu. Dodavanje ili preimenovanje headera znaci uredivanje svakog handlera, a dokumentacija odmah postane neusklacena cim se jedan propusti.
Good example
| 1 | // api-hmac-or-token-headers.decorator.ts |
| 2 | export function ApiHmacOrTokenHeaders() { |
| 3 | return applyDecorators( |
| 4 | ApiHeader({ name: 'x-api-key', description: 'HMAC API key', required: false }), |
| 5 | ApiHeader({ name: 'token', description: 'MWS authorization token', required: false }), |
| 6 | ApiHeader({ name: 'x-auth-token', description: 'Authorization token', required: false }), |
| 7 | ); |
| 8 | } |
| 9 |
|
| 10 | // controller |
| 11 | @Get() |
| 12 | @ApiHmacOrTokenHeaders() |
| 13 | getA() {} |
| 14 |
|
| 15 | @Post() |
| 16 | @ApiHmacOrTokenHeaders() |
| 17 | postB() {} |
Explanation (EN)
The header contract is defined once and reused by name. Endpoints stay readable, and changing the auth headers is a single edit that propagates everywhere. Pairing the decorator name with the guard it documents (e.g. HmacOrTokenGuard) keeps docs and runtime auth in sync.
Objašnjenje (HR)
Ugovor za headere definiran je jednom i koristi se po imenu. Endpointi ostaju citljivi, a promjena auth headera je jedna izmjena koja se propagira svuda. Povezivanje imena dekoratora s guardom koji dokumentira (npr. HmacOrTokenGuard) drzi dokumentaciju i runtime auth usklacenima.
Notes (EN)
applyDecorators() composes any decorators, not just Swagger ones (guards, interceptors, HttpCode). The same idea applies to repeated @ApiResponse error blocks via an ApiCommonErrorResponses() helper.
Bilješke (HR)
applyDecorators() komponira bilo koje dekoratore, ne samo Swagger (guardove, interceptore, HttpCode). Ista ideja vrijedi za ponovljene @ApiResponse error blokove preko ApiCommonErrorResponses() helpera.