nxxmdata/backend/swagger-auth.js

/**
 * 认证模块 Swagger 文档
 * @file swagger-auth.js
 * @description 用户认证相关的 Swagger API 文档定义
 */

// 认证相关的 API 路径定义
const authPaths = {
  '/api/auth/login': {
    post: {
      summary: '用户登录',
      tags: ['用户认证'],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: { $ref: '#/components/schemas/LoginRequest' }
          }
        }
      },
      responses: {
        200: { $ref: '#/components/responses/Success' },
        401: { $ref: '#/components/responses/Unauthorized' }
      }
    }
  },
  '/api/auth/register': {
    post: {
      summary: '用户注册',
      tags: ['用户认证'],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: { $ref: '#/components/schemas/RegisterRequest' }
          }
        }
      },
      responses: {
        201: { $ref: '#/components/responses/Created' },
        400: { $ref: '#/components/responses/BadRequest' }
      }
    }
  },
  '/api/auth/me': {
    get: {
      summary: '获取当前用户信息',
      tags: ['用户认证'],
      security: [{ bearerAuth: [] }],
      responses: {
        200: { $ref: '#/components/responses/Success' },
        401: { $ref: '#/components/responses/Unauthorized' }
      }
    }
  },
  '/api/auth/validate': {
    get: {
      summary: '验证Token有效性',
      tags: ['用户认证'],
      security: [{ bearerAuth: [] }],
      responses: {
        200: { $ref: '#/components/responses/Success' },
        401: { $ref: '#/components/responses/Unauthorized' }
      }
    }
  },
  '/api/auth/roles': {
    get: {
      summary: '获取所有角色',
      tags: ['用户认证'],
      security: [{ bearerAuth: [] }],
      responses: {
        200: { $ref: '#/components/responses/Success' }
      }
    }
  },
  '/api/auth/users/{userId}/roles': {
    post: {
      summary: '为用户分配角色',
      tags: ['用户认证'],
      security: [{ bearerAuth: [] }],
      parameters: [
        { 
          name: 'userId', 
          in: 'path', 
          required: true, 
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['roleId'],
              properties: {
                roleId: { type: 'integer', description: '角色ID' }
              }
            }
          }
        }
      },
      responses: {
        200: { $ref: '#/components/responses/Success' },
        400: { $ref: '#/components/responses/BadRequest' },
        403: { $ref: '#/components/responses/Forbidden' }
      }
    }
  },
  '/api/auth/users/{userId}/roles/{roleId}': {
    delete: {
      summary: '移除用户的角色',
      tags: ['用户认证'],
      security: [{ bearerAuth: [] }],
      parameters: [
        { 
          name: 'userId', 
          in: 'path', 
          required: true, 
          schema: { type: 'integer' },
          description: '用户ID'
        },
        { 
          name: 'roleId', 
          in: 'path', 
          required: true, 
          schema: { type: 'integer' },
          description: '角色ID'
        }
      ],
      responses: {
        200: { $ref: '#/components/responses/Success' },
        404: { $ref: '#/components/responses/NotFound' }
      }
    }
  }
};

// 认证相关的数据模型定义
const authSchemas = {
  LoginRequest: {
    type: 'object',
    required: ['username', 'password'],
    properties: {
      username: { type: 'string', description: '用户名或邮箱' },
      password: { type: 'string', format: 'password', description: '密码' }
    }
  },
  LoginResponse: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string' },
      token: { type: 'string', description: 'JWT令牌' },
      user: { $ref: '#/components/schemas/User' },
      permissions: { 
        type: 'array', 
        items: { type: 'string' },
        description: '用户权限列表'
      },
      accessibleMenus: { 
        type: 'array', 
        items: { type: 'string' },
        description: '可访问的菜单列表'
      }
    }
  },
  RegisterRequest: {
    type: 'object',
    required: ['username', 'email', 'password'],
    properties: {
      username: { type: 'string', description: '用户名' },
      email: { type: 'string', format: 'email', description: '邮箱地址' },
      password: { type: 'string', format: 'password', description: '密码' }
    }
  },
  RegisterResponse: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string' },
      user: { $ref: '#/components/schemas/User' }
    }
  },
  Role: {
    type: 'object',
    properties: {
      id: { type: 'integer', description: '角色ID' },
      name: { type: 'string', description: '角色名称' },
      description: { type: 'string', description: '角色描述' }
    }
  }
};

module.exports = {
  authPaths,
  authSchemas
};