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).
Update the response DTO when adding new response fields
When an endpoint returns new fields, declare them on its response DTO/schema so serialization and API docs stay correct.
Bad example
| 1 | // Service now returns `containedInPortfolioIds`, but the DTO was never updated |
| 2 | export class IsInstrumentInPortfolioDto { |
| 3 | portfolioId: number; |
| 4 | portfolioName: string; |
| 5 | // containedInPortfolioIds: number[] <-- missing! |
| 6 | } |
| 7 |
|
| 8 | @Get('has-instrument/:insref') |
| 9 | @ApiOkResponse({ type: IsInstrumentInPortfolioDto, isArray: true }) |
| 10 | async getIsInstrumentInPortfolio(): Promise<IsInstrumentInPortfolioDto[]> { |
| 11 | return this.service.getIsInstrumentInPortfolio(insref); // extra field silently stripped |
| 12 | } |
Explanation (EN)
The handler produces a field the DTO does not declare, so a class-serializer/`@ApiOkResponse` pipeline strips it and the OpenAPI docs advertise a wrong shape. Clients never see the new data.
Objašnjenje (HR)
Handler vraca polje koje DTO ne deklarira, pa ga serializacijski sloj izbacuje, a OpenAPI dokumentacija oglasava krivi oblik. Klijenti nikad ne vide nove podatke.
Good example
| 1 | export class IsInstrumentInPortfolioDto { |
| 2 | portfolioId: number; |
| 3 | portfolioName: string; |
| 4 | containedInPortfolioIds: number[]; // declared alongside the new behaviour |
| 5 | } |
| 6 |
|
| 7 | @Get('has-instrument/:insref') |
| 8 | @ApiOkResponse({ type: IsInstrumentInPortfolioDto, isArray: true }) |
| 9 | async getIsInstrumentInPortfolio(): Promise<IsInstrumentInPortfolioDto[]> { |
| 10 | return this.service.getIsInstrumentInPortfolio(insref); |
| 11 | } |
Explanation (EN)
The DTO declares every field the endpoint actually returns, so serialization preserves it and the generated API docs match the real response.
Objašnjenje (HR)
DTO deklarira svako polje koje endpoint stvarno vraca, pa ga serijalizacija cuva, a generirana dokumentacija odgovara stvarnom odgovoru.
Notes (EN)
Treat the response DTO as the single source of truth for the contract; updating handler logic and the DTO should be one atomic change.
Bilješke (HR)
Tretiraj response DTO kao jedini izvor istine za ugovor; izmjena logike handlera i DTO-a treba biti jedna atomarna promjena.