/** * @file Swagger插件封装 * @author hotok * @date 2025-06-28 * @lastEditor hotok * @lastEditTime 2025-06-28 * @description 封装Elysia Swagger插件，统一管理API文档配置，包含全局响应示例和错误码说明 */ import { swagger } from '@elysiajs/swagger'; /** * Swagger插件实例 * @description 统一API文档配置，包含全局响应组件、错误码说明等 */ export const swaggerPlugin = swagger({ path: '/docs', documentation: { info: { title: 'Cursor Init API服务', version: '1.0.0', description: ` # Cursor Init API服务 基于 **Elysia + Bun.js** 构建的高性能API服务，集成以下功能： ## 🚀 核心特性 - **JWT认证**: 完整的用户认证和授权体系 - **MySQL数据库**: 数据持久化和高性能查询 - **Redis缓存**: 分布式缓存和会话管理 - **Winston日志**: 结构化日志记录和监控 - **健康检查**: 系统和依赖服务状态监控 - **统一响应**: 标准化的API响应格式 - **参数验证**: 严格的输入参数校验 - **错误处理**: 全局异常捕获和友好错误信息 ## 📋 错误码说明 | 错误码 | 说明 | 示例场景 | |--------|------|----------| | 0 | 操作成功 | 正常业务流程 | | 400 | 业务逻辑错误 | 用户名已存在、余额不足等 | | 401 | 身份认证失败 | Token无效、未登录等 | | 403 | 权限不足 | 无操作权限、角色限制等 | | 404 | 资源未找到 | 用户不存在、页面不存在等 | | 422 | 参数验证失败 | 邮箱格式错误、必填参数缺失等 | | 500 | 服务器内部错误 | 数据库异常、系统故障等 | | 503 | 服务不可用 | 系统维护、依赖服务异常等 | ## 🔐 认证说明 大部分接口需要JWT认证，请在请求头中添加： \`\`\` Authorization: Bearer \`\`\` ## 📝 响应格式 所有API响应均采用统一格式： \`\`\`json { "code": 0, "message": "操作成功", "data": { // 具体数据 } } \`\`\` ## 🔗 相关链接 - [健康检查](/api/health) - 系统健康状态 - [详细健康检查](/api/health/detailed) - 包含性能指标的详细状态 `, contact: { name: 'API支持', email: 'support@example.com', url: 'https://github.com/your-org/cursor-init', }, license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT', }, termsOfService: 'https://example.com/terms', }, servers: [ { url: 'http://localhost:3000', description: '开发环境', }, { url: 'https://api.example.com', description: '生产环境', }, ], components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT', description: ` JWT认证说明： 1. 通过登录接口获取JWT token 2. 在需要认证的接口请求头中添加：Authorization: Bearer 3. Token有效期为24小时，过期后需重新登录 4. Token格式：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... **示例：** \`\`\` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c \`\`\` `, }, }, schemas: { BaseResponse: { type: 'object', description: '基础响应结构', required: ['code', 'message', 'data'], properties: { code: { type: 'number', description: '响应码，0表示成功，其他表示错误', example: 0, }, message: { type: 'string', description: '响应消息，描述操作结果', example: '操作成功', }, data: { description: '响应数据，成功时包含具体数据，失败时通常为null', }, }, }, SuccessResponse: { type: 'object', description: '成功响应', required: ['code', 'message', 'data'], properties: { code: { type: 'number', enum: [0], description: '成功响应码', }, message: { type: 'string', description: '成功消息', example: '操作成功', }, data: { description: '成功时返回的数据', }, }, }, ErrorResponse: { type: 'object', description: '错误响应', required: ['code', 'message', 'data'], properties: { code: { type: 'number', description: '错误响应码', example: 400, }, message: { type: 'string', description: '错误消息', example: '参数验证失败', }, data: { type: 'null', description: '错误时数据字段为null', }, }, }, PaginationResponse: { type: 'object', description: '分页响应', required: ['code', 'message', 'data'], properties: { code: { type: 'number', enum: [0], }, message: { type: 'string', }, data: { type: 'object', required: ['list', 'pagination'], properties: { list: { type: 'array', description: '数据列表', items: {}, }, pagination: { type: 'object', description: '分页信息', required: ['page', 'pageSize', 'total', 'totalPages', 'hasNext', 'hasPrev'], properties: { page: { type: 'number', description: '当前页码，从1开始', minimum: 1, examples: [1, 2, 3], }, pageSize: { type: 'number', description: '每页条数', minimum: 1, maximum: 100, examples: [10, 20, 50], }, total: { type: 'number', description: '总条数', minimum: 0, examples: [0, 100, 1500], }, totalPages: { type: 'number', description: '总页数', minimum: 0, examples: [0, 5, 75], }, hasNext: { type: 'boolean', description: '是否有下一页', }, hasPrev: { type: 'boolean', description: '是否有上一页', }, }, }, }, }, }, }, }, responses: { Success: { description: '操作成功', content: { 'application/json': { schema: { $ref: '#/components/schemas/SuccessResponse', }, examples: { default: { summary: '成功示例', value: { code: 0, message: '操作成功', data: { id: 1, name: '示例数据', }, }, }, }, }, }, }, BadRequest: { description: '业务逻辑错误', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '业务错误示例', value: { code: 400, message: '用户名已存在', data: null, }, }, }, }, }, }, Unauthorized: { description: '身份认证失败', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { tokenExpired: { summary: 'Token过期', value: { code: 401, message: 'Token已过期，请重新登录', data: null, }, }, tokenInvalid: { summary: 'Token无效', value: { code: 401, message: 'Token格式错误或无效', data: null, }, }, notLoggedIn: { summary: '未登录', value: { code: 401, message: '请先登录', data: null, }, }, }, }, }, }, Forbidden: { description: '权限不足', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '权限不足示例', value: { code: 403, message: '权限不足，无法访问该资源', data: null, }, }, }, }, }, }, NotFound: { description: '资源未找到', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '资源不存在示例', value: { code: 404, message: '请求的资源不存在', data: null, }, }, }, }, }, }, ValidationError: { description: '参数验证失败', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '参数验证失败示例', value: { code: 422, message: '邮箱格式不正确', data: null, }, }, }, }, }, }, InternalError: { description: '服务器内部错误', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '服务器错误示例', value: { code: 500, message: '服务器内部错误，请稍后重试', data: null, }, }, }, }, }, }, ServiceUnavailable: { description: '服务不可用', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse', }, examples: { default: { summary: '服务不可用示例', value: { code: 503, message: '服务暂时不可用，请稍后重试', data: null, }, }, }, }, }, }, }, }, security: [{ bearerAuth: [] }], tags: [ { name: '认证管理', description: '用户认证相关接口，包括登录、注册、Token验证等', }, { name: '用户管理', description: '用户信息管理接口', }, { name: '健康检查', description: '系统健康状态监控接口', }, ], }, });