Documentation Conventions

When adding a public endpoint:

1. 1Annotate the controller with @ApiTags(SWAGGER_TAGS.*).
2. 2Add @ApiOperation({ summary, description }).
3. 3Document success and relevant error responses.
4. 4Apply @ApiDocsMetadata({ category, group, order, ... }) for hierarchy.
5. 5Document DTO fields with @ApiProperty (descriptions/examples; fake values only).
6. 6Exclude sensitive fields from response schemas.
7. 7Confirm the operation appears in this portal after regenerating OpenAPI.
8. 8Run pnpm docs:validate (or the API docs quality tests).

Use x-arvexa-docs-hidden: true via @ApiDocsMetadata({ hidden: true }) for internal probes that must not appear in the portal.