aijianhua/backend/config/swagger.js

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

// Swagger 配置选项
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '爱鉴花 API 文档',
      version: '1.0.0',
      description: '爱鉴花小程序和后端管理系统的 RESTful API 文档',
      contact: {
        name: '技术支持',
        email: 'support@aijianhua.com'
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT'
      }
    },
    servers: [
      {
        url: 'http://localhost:3200/api/v1',
        description: '开发环境'
      },
      {
        url: 'https://api.aijianhua.com/api/v1',
        description: '生产环境'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      },
      schemas: {
        User: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            username: {
              type: 'string',
              example: 'user123'
            },
            phone: {
              type: 'string',
              example: '13800138000'
            },
            email: {
              type: 'string',
              example: 'user@example.com'
            },
            user_type: {
              type: 'string',
              example: 'farmer'
            },
            avatar_url: {
              type: 'string',
              example: 'https://example.com/avatar.jpg'
            },
            created_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            },
            last_login: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            }
          }
        },
        Product: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            name: {
              type: 'string',
              example: '玫瑰花'
            },
            category_id: {
              type: 'integer',
              example: 1
            },
            category_name: {
              type: 'string',
              example: '鲜花'
            },
            price: {
              type: 'number',
              example: 29.9
            },
            stock: {
              type: 'integer',
              example: 100
            },
            image: {
              type: 'string',
              example: 'https://example.com/product.jpg'
            },
            description: {
              type: 'string',
              example: '新鲜玫瑰花'
            },
            status: {
              type: 'integer',
              example: 1
            },
            created_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            },
            updated_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            }
          }
        },
        Order: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            order_number: {
              type: 'string',
              example: 'ORD202301010001'
            },
            user_id: {
              type: 'integer',
              example: 1
            },
            total_amount: {
              type: 'number',
              example: 99.9
            },
            payment_status: {
              type: 'integer',
              example: 1
            },
            shipping_status: {
              type: 'integer',
              example: 0
            },
            shipping_address: {
              type: 'string',
              example: '北京市朝阳区xxx街道xxx号'
            },
            created_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            },
            updated_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            }
          }
        },
        OrderItem: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            order_id: {
              type: 'integer',
              example: 1
            },
            product_id: {
              type: 'integer',
              example: 1
            },
            quantity: {
              type: 'integer',
              example: 2
            },
            price: {
              type: 'number',
              example: 29.9
            }
          }
        },
        CartItem: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            user_id: {
              type: 'integer',
              example: 1
            },
            product_id: {
              type: 'integer',
              example: 1
            },
            product_name: {
              type: 'string',
              example: '玫瑰花'
            },
            product_image: {
              type: 'string',
              example: 'https://example.com/product.jpg'
            },
            price: {
              type: 'number',
              example: 29.9
            },
            quantity: {
              type: 'integer',
              example: 2
            },
            stock: {
              type: 'integer',
              example: 100
            },
            created_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            },
            updated_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            }
          }
        },
        Address: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            user_id: {
              type: 'integer',
              example: 1
            },
            recipient: {
              type: 'string',
              example: '张三'
            },
            phone: {
              type: 'string',
              example: '13800138000'
            },
            province: {
              type: 'string',
              example: '北京市'
            },
            city: {
              type: 'string',
              example: '北京市'
            },
            district: {
              type: 'string',
              example: '朝阳区'
            },
            detail: {
              type: 'string',
              example: 'xxx街道xxx号'
            },
            is_default: {
              type: 'integer',
              example: 1
            },
            created_at: {
              type: 'string',
              format: 'date-time',
              example: '2023-01-01T00:00:00Z'
            }
          }
        },
        Pagination: {
          type: 'object',
          properties: {
            page: {
              type: 'integer',
              example: 1
            },
            limit: {
              type: 'integer',
              example: 10
            },
            total: {
              type: 'integer',
              example: 100
            },
            pages: {
              type: 'integer',
              example: 10
            }
          }
        }
      }
    },
    security: [
      {
        bearerAuth: []
      }
    ]
  },
  apis: ['./routes/*.js'] // 扫描路由文件中的 Swagger 注释
};

const specs = swaggerJSDoc(options);

module.exports = { specs, swaggerUi };