[BE-85] Swagger completeness audit — response schemas and auth annotations

[yusuftomilola]

Overview

@nestjs/swagger is installed and mounted, but coverage is uneven: many endpoints lack @ApiResponse schemas, @ApiBearerAuth, or DTO property decorators, so the generated docs understate the real contract.

Tasks

• Audit every registered controller; add @ApiTags, @ApiOperation, and @ApiResponse for success and documented failure codes.
• Add @ApiProperty to all DTO fields with example values and required flags.
• Add @ApiBearerAuth() to protected routes and configure the security scheme in main.ts.
• Document the standard error shape from [BE-82] as a reusable schema.
• Enable swagger-ui "Try it out" against a local server and verify a few calls actually work from the docs page.

Acceptance Criteria

• Every registered endpoint appears in Swagger with request and response schemas.
• Protected endpoints show the padlock and accept a bearer token in the UI.
• No endpoint shows an empty or any response schema.

Notes for Contributors

Comment below to be assigned.