update swagger

src/swagger/decorators/swagger-response.decorator.ts

@@ -0,0 +1,125 @@
+import { applyDecorators, Type } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiExtraModels,
+  ApiForbiddenResponse,
+  ApiInternalServerErrorResponse,
+  ApiNotFoundResponse,
+  ApiOkResponse,
+  ApiTooManyRequestsResponse,
+  ApiUnauthorizedResponse,
+  getSchemaPath,
+} from '@nestjs/swagger';
+import {
+  ApiErrorResponseDto,
+  ApiSuccessResponseDto,
+} from '../../common/dto/api-response.dto';
+
+export function ApiStandardController() {
+  return applyDecorators(
+    ApiExtraModels(ApiSuccessResponseDto, ApiErrorResponseDto),
+    ApiStandardErrorResponses(),
+  );
+}
+
+export function ApiStandardErrorResponses() {
+  return applyDecorators(
+    ApiBadRequestResponse({
+      description: 'Validation failed or bad request',
+      type: ApiErrorResponseDto,
+    }),
+    ApiUnauthorizedResponse({
+      description: 'Unauthorized',
+      type: ApiErrorResponseDto,
+    }),
+    ApiForbiddenResponse({
+      description: 'Forbidden',
+      type: ApiErrorResponseDto,
+    }),
+    ApiNotFoundResponse({
+      description: 'Resource not found',
+      type: ApiErrorResponseDto,
+    }),
+    ApiInternalServerErrorResponse({
+      description: 'Internal server error',
+      type: ApiErrorResponseDto,
+    }),
+  );
+}
+
+export const ApiStandardOkResponse = <TModel extends Type<unknown>>(
+  model: TModel,
+  options?: { isArray?: boolean; nullable?: boolean },
+) =>
+  applyDecorators(
+    ApiExtraModels(ApiSuccessResponseDto, model),
+    ApiOkResponse({
+      description: 'Successful response',
+      schema: {
+        allOf: [
+          { $ref: getSchemaPath(ApiSuccessResponseDto) },
+          {
+            properties: {
+              data: options?.nullable
+                ? { type: 'null', nullable: true }
+                : options?.isArray
+                  ? {
+                      type: 'array',
+                      items: { $ref: getSchemaPath(model) },
+                    }
+                  : { $ref: getSchemaPath(model) },
+            },
+          },
+        ],
+      },
+    }),
+  );
+
+export function ApiStandardEmptyResponse() {
+  return applyDecorators(
+    ApiExtraModels(ApiSuccessResponseDto),
+    ApiOkResponse({
+      description: 'Successful response with no data',
+      schema: {
+        allOf: [
+          { $ref: getSchemaPath(ApiSuccessResponseDto) },
+          {
+            properties: {
+              data: { type: 'null', nullable: true },
+            },
+          },
+        ],
+      },
+    }),
+  );
+}
+
+export function ApiStandardMessageResponse(example = 'Operation completed') {
+  return applyDecorators(
+    ApiExtraModels(ApiSuccessResponseDto),
+    ApiOkResponse({
+      description: 'Successful response with message only',
+      schema: {
+        allOf: [
+          { $ref: getSchemaPath(ApiSuccessResponseDto) },
+          {
+            properties: {
+              message: { type: 'string', example },
+              data: { type: 'null', nullable: true },
+            },
+          },
+        ],
+      },
+    }),
+  );
+}
+
+export function ApiStandardTooManyRequestsResponse() {
+  return applyDecorators(
+    ApiExtraModels(ApiErrorResponseDto),
+    ApiTooManyRequestsResponse({
+      description: 'Too many requests',
+      type: ApiErrorResponseDto,
+    }),
+  );
+}

src/swagger/swagger.setup.ts

@@ -1,12 +1,21 @@
 import { INestApplication } from '@nestjs/common';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import {
+  ApiErrorResponseDto,
+  ApiSuccessResponseDto,
+} from '../common/dto/api-response.dto';
 
 export const SWAGGER_JWT_AUTH = 'access-token';
 
 export function setupSwagger(app: INestApplication): void {
   const config = new DocumentBuilder()
     .setTitle('Grow API')
-    .setDescription('BeautyBook Grow API documentation')
+    .setDescription(
+      'BeautyBook Grow API documentation.\n\n' +
+        'All API responses follow a standard envelope:\n' +
+        '- Success: `{ success: true, data, message?, meta? }`\n' +
+        '- Error: `{ success: false, statusCode, message, errors?, timestamp, path }`',
+    )
     .setVersion('1.0')
     .addBearerAuth(
       {
@@ -19,7 +28,9 @@ export function setupSwagger(app: INestApplication): void {
     )
     .build();
 
-  const document = SwaggerModule.createDocument(app, config);
+  const document = SwaggerModule.createDocument(app, config, {
+    extraModels: [ApiSuccessResponseDto, ApiErrorResponseDto],
+  });
 
   SwaggerModule.setup('docs', app, document, {
     jsonDocumentUrl: 'docs-json',