Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(auth): declare the 400 and 404 the API key routes return

Yudhi Armyndharise7df109cdbd5
diff --git a/src/modules/auth/auth.controller.spec.ts b/src/modules/auth/auth.controller.spec.ts
index 4e2bf41c5..7aaee27b0 100644
--- a/src/modules/auth/auth.controller.spec.ts
+++ b/src/modules/auth/auth.controller.spec.ts
@@ -16,6 +16,26 @@ describe('AuthController — scoped-key confinement marker', () => {
});
});
+// Every route that loads a key by id answers 404 for an unknown one, and every route with a body
+// answers 400 on validation: the contract must say so, or a generated client has no case for them.
+describe('AuthController OpenAPI error responses', () => {
+ const declared = (handler: keyof AuthController) =>
+ Object.keys(
+ (Reflect.getMetadata(
+ 'swagger/apiResponse',
+ Object.getOwnPropertyDescriptor(AuthController.prototype, handler)?.value as object,
+ ) ?? {}) as Record<string, unknown>,
+ );
+
+ it.each(['findOne', 'update', 'delete', 'revoke'] as const)('declares 404 on %s', handler => {
+ expect(declared(handler)).toContain('404');
+ });
+
+ it.each(['create', 'update'] as const)('declares 400 on %s', handler => {
+ expect(declared(handler)).toContain('400');
+ });
+});
+
// API-key lifecycle operations (create / delete / revoke) must leave an audit trail — they were
// previously unrecorded. These assert the controller emits the matching audit action with the acting
// admin key, the resolved client IP, and the target key in metadata.
diff --git a/src/modules/auth/auth.controller.ts b/src/modules/auth/auth.controller.ts
index 424b22a93..e2766f39f 100644
--- a/src/modules/auth/auth.controller.ts
+++ b/src/modules/auth/auth.controller.ts
@@ -53,6 +53,7 @@ export class AuthController {
description: 'API key created',
type: ApiKeyCreatedResponseDto,
})
+ @ApiResponse({ status: 400, description: 'Validation failed, or the body carries a field the DTO does not declare.' })
async create(
@Body() dto: CreateApiKeyDto,
@Req() req: Request,
@@ -119,6 +120,7 @@ export class AuthController {
description: 'The API key (plaintext never returned; only the keyPrefix).',
type: ApiKeyResponseDto,
})
+ @ApiResponse({ status: 404, description: 'No API key with this id.' })
async findOne(@Param('id') id: string): Promise<ApiKeyResponseDto> {
const k = await this.authService.findOne(id);
return {
@@ -141,6 +143,8 @@ export class AuthController {
@RequireRole(ApiKeyRole.ADMIN)
@ApiOperation({ summary: 'Update API key (admin only)' })
@ApiResponse({ status: 200, description: 'The updated API key.', type: ApiKeyResponseDto })
+ @ApiResponse({ status: 400, description: 'Validation failed, or the body carries a field the DTO does not declare.' })
+ @ApiResponse({ status: 404, description: 'No API key with this id.' })
@ApiResponse({
status: 409,
description: 'The change would remove the last usable admin key: no other usable admin key lasts at least as long.',
@@ -183,6 +187,7 @@ export class AuthController {
@HttpCode(HttpStatus.NO_CONTENT)
@ApiOperation({ summary: 'Delete API key (admin only)' })
@ApiResponse({ status: 204, description: 'API key deleted' })
+ @ApiResponse({ status: 404, description: 'No API key with this id.' })
@ApiResponse({
status: 409,
description: 'The key is the last usable admin key: no other usable admin key lasts at least as long.',
@@ -201,6 +206,7 @@ export class AuthController {
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Revoke API key (admin only)' })
@ApiResponse({ status: 200, description: 'The revoked API key (isActive now false).', type: ApiKeyResponseDto })
+ @ApiResponse({ status: 404, description: 'No API key with this id.' })
@ApiResponse({
status: 409,
description: 'The key is the last usable admin key: no other usable admin key lasts at least as long.',