swagger

2025-04-02 11:50:08 -06:00
parent bf7c0e93a8
commit a1f52daa8a
26 changed files with 1109 additions and 42 deletions
@@ -0,0 +1,185 @@
+import { ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { applyDecorators } from '@nestjs/common';
+
+export class SeccionApiDocumentation {
+  // Decoradores para toda la clase del controlador
+  static ApiController = ApiTags('Secciones');
+
+  // Documentación para crear una sección
+  static ApiCreate = applyDecorators(
+    ApiOperation({
+      summary: 'Crear una nueva sección',
+      description: 'Crea una nueva sección para un cuestionario'
+    }),
+    ApiBody({
+      description: 'Datos de la sección a crear',
+      schema: {
+        type: 'object',
+        required: ['titulo'],
+        properties: {
+          titulo: { type: 'string', example: 'Información Personal' },
+          descripcion: { 
+            type: 'string', 
+            example: 'Proporciona tus datos personales para poder contactarte'
+          },
+          contador_pregunta: { type: 'number', example: 0 },
+          preguntas: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                titulo: { type: 'string', example: '¿Eres parte de la comunidad?' },
+                obligatoria: { type: 'boolean', example: true },
+                tipo: { type: 'string', example: 'Multiple' },
+                opciones: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      valor: { type: 'string', example: 'Si' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }),
+    ApiResponse({ 
+      status: 201, 
+      description: 'Sección creada correctamente',
+      schema: {
+        type: 'object',
+        properties: {
+          id_seccion: { type: 'number', example: 1 },
+          titulo: { type: 'string', example: 'Información Personal' },
+          descripcion: { type: 'string' },
+          contador_pregunta: { type: 'number', example: 0 }
+        }
+      }
+    }),
+    ApiResponse({ status: 400, description: 'Datos de la sección inválidos' }),
+    ApiResponse({ status: 500, description: 'Error interno del servidor' })
+  );
+
+  // Documentación para obtener todas las secciones
+  static ApiGetAll = applyDecorators(
+    ApiOperation({
+      summary: 'Obtener todas las secciones',
+      description: 'Retorna una lista de todas las secciones registradas'
+    }),
+    ApiResponse({
+      status: 200,
+      description: 'Lista de secciones obtenida correctamente',
+      schema: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id_seccion: { type: 'number', example: 1 },
+            titulo: { type: 'string', example: 'Información Personal' },
+            descripcion: { type: 'string' },
+            contador_pregunta: { type: 'number', example: 0 }
+          }
+        }
+      }
+    }),
+    ApiResponse({ status: 500, description: 'Error interno del servidor' })
+  );
+
+  // Documentación para obtener una sección por ID
+  static ApiGetOne = applyDecorators(
+    ApiOperation({
+      summary: 'Obtener una sección por ID',
+      description: 'Retorna una sección específica por su ID'
+    }),
+    ApiParam({
+      name: 'id',
+      description: 'ID de la sección',
+      required: true,
+      type: 'number',
+      example: 1
+    }),
+    ApiResponse({
+      status: 200,
+      description: 'Sección obtenida correctamente',
+      schema: {
+        type: 'object',
+        properties: {
+          id_seccion: { type: 'number', example: 1 },
+          titulo: { type: 'string', example: 'Información Personal' },
+          descripcion: { type: 'string' },
+          contador_pregunta: { type: 'number', example: 0 }
+        }
+      }
+    }),
+    ApiResponse({ status: 404, description: 'Sección no encontrada' }),
+    ApiResponse({ status: 500, description: 'Error interno del servidor' })
+  );
+
+  // Documentación para actualizar una sección
+  static ApiUpdate = applyDecorators(
+    ApiOperation({
+      summary: 'Actualizar una sección',
+      description: 'Actualiza los datos de una sección existente'
+    }),
+    ApiParam({
+      name: 'id',
+      description: 'ID de la sección a actualizar',
+      required: true,
+      type: 'number',
+      example: 1
+    }),
+    ApiBody({
+      description: 'Datos a actualizar de la sección',
+      schema: {
+        type: 'object',
+        properties: {
+          titulo: { type: 'string', example: 'Título actualizado' },
+          descripcion: { type: 'string', example: 'Descripción actualizada' }
+        }
+      }
+    }),
+    ApiResponse({
+      status: 200,
+      description: 'Sección actualizada correctamente',
+      schema: {
+        type: 'object',
+        properties: {
+          affected: { type: 'number', example: 1 }
+        }
+      }
+    }),
+    ApiResponse({ status: 400, description: 'Datos de actualización inválidos' }),
+    ApiResponse({ status: 404, description: 'Sección no encontrada' }),
+    ApiResponse({ status: 500, description: 'Error interno del servidor' })
+  );
+
+  // Documentación para eliminar una sección
+  static ApiRemove = applyDecorators(
+    ApiOperation({
+      summary: 'Eliminar una sección',
+      description: 'Elimina permanentemente una sección por su ID'
+    }),
+    ApiParam({
+      name: 'id',
+      description: 'ID de la sección a eliminar',
+      required: true,
+      type: 'number',
+      example: 1
+    }),
+    ApiResponse({
+      status: 200,
+      description: 'Sección eliminada correctamente',
+      schema: {
+        type: 'object',
+        properties: {
+          affected: { type: 'number', example: 1 }
+        }
+      }
+    }),
+    ApiResponse({ status: 404, description: 'Sección no encontrada' }),
+    ApiResponse({ status: 500, description: 'Error interno del servidor' })
+  );
+}