nxxmdata/backend/swagger-auth.js

/**
 * 用户认证模块 Swagger 文档
 * @file swagger-auth.js
 */

const authPaths = {
  // 用户登录
  '/auth/login': {
    post: {
      tags: ['用户认证'],
      summary: '用户登录',
      description: '用户通过用户名/邮箱和密码登录系统',
      security: [], // 登录接口不需要认证
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['username', 'password'],
              properties: {
                username: {
                  type: 'string',
                  description: '用户名或邮箱',
                  example: 'admin'
                },
                password: {
                  type: 'string',
                  description: '密码',
                  example: '123456'
                }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '登录成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '登录成功' },
                  token: { type: 'string', description: 'JWT Token' },
                  user: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      username: { type: 'string' },
                      email: { type: 'string' },
                      phone: { type: 'string' },
                      avatar: { type: 'string' },
                      status: { type: 'string' },
                      roles: { type: 'array', items: { type: 'object' } }
                    }
                  }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '401': {
          description: '用户名或密码错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '429': {
          description: '登录尝试次数过多，请稍后再试',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 用户注册
  '/auth/register': {
    post: {
      tags: ['用户认证'],
      summary: '用户注册',
      description: '新用户注册账号',
      security: [], // 注册接口不需要认证
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['username', 'email', 'password'],
              properties: {
                username: {
                  type: 'string',
                  description: '用户名',
                  example: 'newuser'
                },
                email: {
                  type: 'string',
                  format: 'email',
                  description: '邮箱地址',
                  example: 'newuser@example.com'
                },
                password: {
                  type: 'string',
                  minLength: 6,
                  description: '密码（至少6位）',
                  example: '123456'
                },
                phone: {
                  type: 'string',
                  description: '手机号码',
                  example: '13800138000'
                }
              }
            }
          }
        }
      },
      responses: {
        '201': {
          description: '注册成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '注册成功' },
                  user: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      username: { type: 'string' },
                      email: { type: 'string' },
                      phone: { type: 'string' }
                    }
                  }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误或用户已存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取当前用户信息
  '/auth/me': {
    get: {
      tags: ['用户认证'],
      summary: '获取当前用户信息',
      description: '获取当前登录用户的详细信息',
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      username: { type: 'string' },
                      email: { type: 'string' },
                      phone: { type: 'string' },
                      avatar: { type: 'string' },
                      status: { type: 'string' },
                      roles: { type: 'array', items: { type: 'object' } },
                      permissions: { type: 'array', items: { type: 'string' } },
                      menus: { type: 'array', items: { type: 'object' } }
                    }
                  }
                }
              }
            }
          }
        },
        '401': {
          description: '未授权，Token无效或已过期',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // Token验证
  '/auth/validate': {
    get: {
      tags: ['用户认证'],
      summary: 'Token验证',
      description: '验证当前Token是否有效',
      responses: {
        '200': {
          description: 'Token有效',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: 'Token有效' },
                  user: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      username: { type: 'string' },
                      email: { type: 'string' }
                    }
                  }
                }
              }
            }
          }
        },
        '401': {
          description: 'Token无效或已过期',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取所有角色
  '/auth/roles': {
    get: {
      tags: ['用户认证'],
      summary: '获取所有角色',
      description: '获取系统中所有可用的角色列表',
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: {
                      type: 'object',
                      properties: {
                        id: { type: 'integer' },
                        name: { type: 'string' },
                        description: { type: 'string' },
                        permissions: { type: 'array', items: { type: 'string' } }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 为用户分配角色
  '/auth/users/{userId}/roles': {
    post: {
      tags: ['用户认证'],
      summary: '为用户分配角色',
      description: '为指定用户分配一个或多个角色',
      parameters: [
        {
          name: 'userId',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['roleIds'],
              properties: {
                roleIds: {
                  type: 'array',
                  items: { type: 'integer' },
                  description: '角色ID列表'
                }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '分配成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '角色分配成功' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '404': {
          description: '用户不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 移除用户角色
  '/auth/users/{userId}/roles/{roleId}': {
    delete: {
      tags: ['用户认证'],
      summary: '移除用户角色',
      description: '移除用户的指定角色',
      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': {
          description: '移除成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '角色移除成功' }
                }
              }
            }
          }
        },
        '404': {
          description: '用户或角色不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  }
};

module.exports = authPaths;