niumalll/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文档',
      description: '活牛采购智能数字化系统的后端API接口文档',
      version: '1.0.0',
      contact: {
        name: 'NiuMall Team',
        email: 'contact@niumall.com'
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT'
      }
    },
    servers: [
      {
        url: 'http://localhost:4330',
        description: '本地开发环境'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      },
      schemas: {
        // 通用响应格式
        ApiResponse: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              description: '请求是否成功'
            },
            message: {
              type: 'string',
              description: '返回消息'
            },
            data: {
              type: 'object',
              description: '返回数据',
              nullable: true
            }
          }
        },
        // 分页数据格式
        PagedResponse: {
          type: 'object',
          properties: {
            items: {
              type: 'array',
              items: {
                type: 'object'
              },
              description: '数据列表'
            },
            total: {
              type: 'integer',
              description: '总条数'
            },
            page: {
              type: 'integer',
              description: '当前页码'
            },
            pageSize: {
              type: 'integer',
              description: '每页条数'
            },
            totalPages: {
              type: 'integer',
              description: '总页数'
            }
          }
        },
        // 订单相关模型
        Order: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              description: '订单ID'
            },
            orderNo: {
              type: 'string',
              description: '订单编号'
            },
            buyerId: {
              type: 'integer',
              description: '买方ID'
            },
            buyerName: {
              type: 'string',
              description: '买方名称'
            },
            supplierId: {
              type: 'integer',
              description: '供应商ID'
            },
            supplierName: {
              type: 'string',
              description: '供应商名称'
            },
            traderId: {
              type: 'integer',
              nullable: true,
              description: '贸易商ID'
            },
            traderName: {
              type: 'string',
              nullable: true,
              description: '贸易商名称'
            },
            cattleBreed: {
              type: 'string',
              description: '牛品种'
            },
            cattleCount: {
              type: 'integer',
              description: '牛数量'
            },
            expectedWeight: {
              type: 'number',
              description: '预计重量'
            },
            actualWeight: {
              type: 'number',
              nullable: true,
              description: '实际重量'
            },
            unitPrice: {
              type: 'number',
              description: '单价'
            },
            totalAmount: {
              type: 'number',
              description: '总金额'
            },
            paidAmount: {
              type: 'number',
              description: '已支付金额'
            },
            remainingAmount: {
              type: 'number',
              description: '剩余金额'
            },
            status: {
              type: 'string',
              enum: ['pending', 'confirmed', 'preparing', 'shipping', 'delivered', 'accepted', 'completed', 'cancelled', 'refunded'],
              description: '订单状态'
            },
            deliveryAddress: {
              type: 'string',
              description: '送货地址'
            },
            expectedDeliveryDate: {
              type: 'string',
              format: 'date',
              description: '预计送达日期'
            },
            actualDeliveryDate: {
              type: 'string',
              format: 'date',
              nullable: true,
              description: '实际送达日期'
            },
            notes: {
              type: 'string',
              nullable: true,
              description: '备注'
            },
            createdAt: {
              type: 'string',
              format: 'date-time',
              description: '创建时间'
            },
            updatedAt: {
              type: 'string',
              format: 'date-time',
              description: '更新时间'
            }
          }
        },
        // 用户相关模型
        User: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              description: '用户ID'
            },
            username: {
              type: 'string',
              description: '用户名'
            },
            email: {
              type: 'string',
              format: 'email',
              description: '邮箱'
            },
            phone: {
              type: 'string',
              description: '手机号'
            },
            user_type: {
              type: 'string',
              enum: ['admin', 'buyer', 'supplier', 'trader'],
              description: '用户类型'
            },
            status: {
              type: 'string',
              enum: ['active', 'inactive', 'suspended'],
              description: '用户状态'
            },
            createdAt: {
              type: 'string',
              format: 'date-time',
              description: '创建时间'
            },
            updatedAt: {
              type: 'string',
              format: 'date-time',
              description: '更新时间'
            }
          }
        }
      }
    }
  },
  // 指定API文档的路径
  apis: ['../routes/*.js']
}

// 初始化Swagger-jsdoc
const specs = swaggerJsdoc(options)

module.exports = {
  specs,
  swaggerUi
}