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).
Keep a DTO field's TypeScript type consistent with its API doc annotation
When a field's Swagger/OpenAPI `type` and its TypeScript type disagree (e.g. documented number but typed string), fix the mismatch so the schema, serialization, and consumers all align.
Bad example
| 1 | export class StatsDto { |
| 2 | @Expose() |
| 3 | @ApiProperty({ type: 'number', example: 5 }) |
| 4 | count: string; // doc says number, type says string |
| 5 | } |
Explanation (EN)
The OpenAPI schema advertises a number while the property is typed as a string, so generated clients and runtime serialization disagree with the documentation.
Objašnjenje (HR)
OpenAPI shema oglasava broj dok je svojstvo tipizirano kao string, pa se generirani klijenti i serijalizacija u izvodenju ne slazu s dokumentacijom.
Good example
| 1 | export class StatsDto { |
| 2 | @Expose() |
| 3 | @ApiProperty({ type: 'number', example: 5 }) |
| 4 | count: number; // type matches the documented schema |
| 5 | } |
Explanation (EN)
Aligning the TypeScript type with the documented `type` keeps the API contract truthful end to end.
Objašnjenje (HR)
Uskladivanje TypeScript tipa s dokumentiranim `type` cuva ugovor API-ja istinitim od pocetka do kraja.