sena_db_api_layer/config/swagger.js

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'SENA School Management API',
      version: '1.0.0',
      description: 'API documentation for SENA School Management System with 200 schools',
      contact: {
        name: 'SENA Team',
        email: 'support@sena.vn',
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT',
      },
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Development server',
      },
      {
        url: 'https://api.sena.vn',
        description: 'Production server',
      },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'Enter JWT token from /api/auth/login',
        },
      },
      schemas: {
        Error: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              example: false,
            },
            message: {
              type: 'string',
              example: 'Error message',
            },
          },
        },
        UserProfile: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              format: 'uuid',
              example: '123e4567-e89b-12d3-a456-426614174000',
            },
            user_id: {
              type: 'string',
              format: 'uuid',
            },
            full_name: {
              type: 'string',
              example: 'Nguyễn Văn A',
            },
            date_of_birth: {
              type: 'string',
              format: 'date',
              example: '2010-01-01',
            },
            gender: {
              type: 'string',
              enum: ['male', 'female', 'other'],
              example: 'male',
            },
            phone: {
              type: 'string',
              example: '0901234567',
            },
            avatar_url: {
              type: 'string',
              example: 'https://example.com/avatar.jpg',
            },
            address: {
              type: 'string',
              example: '123 Đường ABC, Quận 1, TP.HCM',
            },
            primary_role_info: {
              type: 'object',
              properties: {
                role_id: { type: 'string', format: 'uuid' },
                role_code: { type: 'string', example: 'student' },
                role_name: { type: 'string', example: 'Học sinh' },
                school: {
                  type: 'object',
                  properties: {
                    id: { type: 'string', format: 'uuid' },
                    name: { type: 'string', example: 'SENA Hà Nội' },
                  },
                },
                class: {
                  type: 'object',
                  properties: {
                    id: { type: 'string', format: 'uuid' },
                    name: { type: 'string', example: 'K1A' },
                  },
                },
                grade: {
                  type: 'object',
                  properties: {
                    id: { type: 'string', format: 'uuid' },
                    name: { type: 'string', example: 'Khối 1' },
                  },
                },
              },
            },
          },
        },
        RoleInfo: {
          type: 'object',
          properties: {
            role_id: {
              type: 'string',
              format: 'uuid',
            },
            role_code: {
              type: 'string',
              example: 'student',
            },
            role_name: {
              type: 'string',
              example: 'Học sinh',
            },
            school: {
              type: 'object',
              nullable: true,
            },
            class: {
              type: 'object',
              nullable: true,
            },
            grade: {
              type: 'object',
              nullable: true,
            },
          },
        },
        Permission: {
          type: 'object',
          properties: {
            code: {
              type: 'string',
              example: 'view_own_grades',
            },
            name: {
              type: 'string',
              example: 'Xem điểm của mình',
            },
            resource: {
              type: 'string',
              example: 'grades',
            },
            action: {
              type: 'string',
              example: 'view',
            },
          },
        },
        Lesson: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              format: 'uuid',
            },
            chapter_id: {
              type: 'string',
              format: 'uuid',
            },
            lesson_number: {
              type: 'integer',
              example: 1,
            },
            lesson_title: {
              type: 'string',
              example: 'Đếm từ 1 đến 5',
            },
            lesson_type: {
              type: 'string',
              enum: ['json_content', 'url_content'],
              example: 'json_content',
            },
            lesson_description: {
              type: 'string',
            },
            content_json: {
              type: 'object',
              description: 'Nội dung bài học dạng JSON',
            },
            content_url: {
              type: 'string',
              description: 'URL nội dung (video, PDF, etc.)',
            },
            content_type: {
              type: 'string',
              example: 'youtube',
            },
            duration_minutes: {
              type: 'integer',
              example: 15,
            },
            is_published: {
              type: 'boolean',
              example: true,
            },
            is_free: {
              type: 'boolean',
              example: true,
            },
            display_order: {
              type: 'integer',
              example: 1,
            },
          },
        },
        Game: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              format: 'uuid',
            },
            title: {
              type: 'string',
              example: 'Trò chơi đếm số',
            },
            description: {
              type: 'string',
            },
            url: {
              type: 'string',
              example: 'https://games.senaai.tech/counting/',
            },
            thumbnail: {
              type: 'string',
            },
            type: {
              type: 'string',
              example: 'counting_quiz',
            },
            config: {
              type: 'object',
            },
            is_active: {
              type: 'boolean',
              example: true,
            },
            is_premium: {
              type: 'boolean',
              example: false,
            },
            difficulty_level: {
              type: 'string',
              enum: ['easy', 'medium', 'hard'],
            },
          },
        },
      },
    },
    tags: [
      {
        name: 'Authentication',
        description: 'User authentication and authorization endpoints',
      },
      {
        name: 'Schools',
        description: 'School management endpoints',
      },
      {
        name: 'Students',
        description: 'Student management endpoints',
      },
      {
        name: 'Teachers',
        description: 'Teacher management endpoints',
      },
      {
        name: 'Lessons',
        description: 'Lesson management endpoints',
      },
      {
        name: 'Chapter Lessons',
        description: 'Get lessons by chapter',
      },
      {
        name: 'Games',
        description: 'Game engine management',
      },
    ],
  },
  apis: ['./controllers/*.js', './routes/*.js'], // Path to the API docs
};

const swaggerSpec = swaggerJsdoc(options);

module.exports = {
  swaggerUi,
  swaggerSpec,
};