feat(backend): 添加 Swagger 文档并优化认证接口

- 在 .env 文件中添加 ENABLE_SWAGGER 环境变量 - 在 app.js 中集成 Swagger UI - 重构 auth 路由，添加请求参数验证 - 更新 API 文档，遵循 OpenAPI 3.0 规范 -优化认证接口的错误处理和响应格式
2025-08-30 15:29:51 +08:00
parent 7f9bfbb381
commit 0cad74b06f
28 changed files with 2123 additions and 691 deletions
--- a/backend/src/config/swagger.js
+++ b/backend/src/config/swagger.js
@@ -0,0 +1,133 @@
+const swaggerJsdoc = require('swagger-jsdoc')
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: '结伴客API文档',
+      version: '1.0.0',
+      description: '结伴客小程序后端API接口文档'
+    },
+    servers: [
+      {
+        url: 'http://localhost:3001/api/v1',
+        description: '开发环境服务器'
+      },
+      {
+        url: 'https://your-domain.com/api/v1',
+        description: '生产环境服务器'
+      }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      },
+      schemas: {
+        User: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'integer',
+              description: '用户ID'
+            },
+            openid: {
+              type: 'string',
+              description: '微信openid'
+            },
+            username: {
+              type: 'string',
+              description: '用户名'
+            },
+            nickname: {
+              type: 'string',
+              description: '昵称'
+            },
+            avatar: {
+              type: 'string',
+              description: '头像URL'
+            },
+            gender: {
+              type: 'string',
+              enum: ['male', 'female', 'other'],
+              description: '性别'
+            },
+            birthday: {
+              type: 'string',
+              format: 'date',
+              description: '生日'
+            },
+            phone: {
+              type: 'string',
+              description: '手机号'
+            },
+            email: {
+              type: 'string',
+              description: '邮箱'
+            },
+            status: {
+              type: 'string',
+              enum: ['active', 'inactive', 'banned'],
+              description: '用户状态'
+            },
+            level: {
+              type: 'integer',
+              description: '用户等级'
+            },
+            points: {
+              type: 'integer',
+              description: '用户积分'
+            },
+            created_at: {
+              type: 'string',
+              format: 'date-time',
+              description: '创建时间'
+            },
+            updated_at: {
+              type: 'string',
+              format: 'date-time',
+              description: '更新时间'
+            }
+          }
+        },
+        ApiResponse: {
+          type: 'object',
+          properties: {
+            success: {
+              type: 'boolean',
+              description: '请求是否成功'
+            },
+            code: {
+              type: 'integer',
+              description: '状态码'
+            },
+            message: {
+              type: 'string',
+              description: '响应消息'
+            },
+            data: {
+              type: 'object',
+              description: '响应数据'
+            }
+          }
+        }
+      }
+    },
+    security: [
+      {
+        bearerAuth: []
+      }
+    ]
+  },
+  apis: [
+    './src/routes/*.js',
+    './src/controllers/*.js'
+  ]
+}
+
+const specs = swaggerJsdoc(options)
+
+module.exports = specs