nxxmdata/bank-backend/config/swagger.js

/**
 * Swagger API文档配置
 * @file swagger.js
 * @description API文档配置和定义
 */
const swaggerJSDoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '银行管理后台API',
      version: '1.1.0',
      description: '银行管理后台系统API文档，包含贷款解押模块',
      contact: {
        name: '银行开发团队',
        email: 'dev@bank.com'
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT'
      }
    },
    servers: [
      {
        url: `http://localhost:${process.env.PORT || 5351}`,
        description: '开发服务器'
      },
      {
        url: 'https://api.bank.com',
        description: '生产服务器'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'JWT访问令牌'
        }
      },
      schemas: {
        Error: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              example: false
            },
            message: {
              type: 'string',
              example: '错误信息'
            },
            errors: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  field: {
                    type: 'string'
                  },
                  message: {
                    type: 'string'
                  }
                }
              }
            }
          }
        },
        Success: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              example: true
            },
            message: {
              type: 'string',
              example: '操作成功'
            },
            data: {
              type: 'object'
            }
          }
        },
        Pagination: {
          type: 'object',
          properties: {
            page: {
              type: 'integer',
              example: 1
            },
            limit: {
              type: 'integer',
              example: 10
            },
            total: {
              type: 'integer',
              example: 100
            },
            pages: {
              type: 'integer',
              example: 10
            }
          }
        },
        LoanRelease: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            applicationNumber: {
              type: 'string',
              example: '20240227145555918'
            },
            productName: {
              type: 'string',
              example: '中国工商银行扎旗支行"畜禽活体抵押"'
            },
            farmerName: {
              type: 'string',
              example: '刘超'
            },
            applicantName: {
              type: 'string',
              example: '刘超'
            },
            applicantIdNumber: {
              type: 'string',
              example: '511123199001013017'
            },
            applicantPhone: {
              type: 'string',
              example: '13800138000'
            },
            assetType: {
              type: 'string',
              example: '牛'
            },
            releaseQuantity: {
              type: 'string',
              example: '10头'
            },
            releaseAmount: {
              type: 'number',
              example: 10000
            },
            status: {
              type: 'string',
              enum: ['pending', 'processing', 'approved', 'rejected', 'completed', 'released'],
              example: 'released'
            },
            applicationTime: {
              type: 'string',
              format: 'date-time',
              example: '2024-02-27T06:55:55.000Z'
            },
            processTime: {
              type: 'string',
              format: 'date-time',
              example: '2024-02-27T07:30:00.000Z'
            },
            completeTime: {
              type: 'string',
              format: 'date-time',
              example: '2024-02-27T08:00:00.000Z'
            },
            processorName: {
              type: 'string',
              example: '系统管理员'
            },
            processComment: {
              type: 'string',
              example: '审核通过，同意解押'
            },
            rejectionReason: {
              type: 'string',
              example: null
            },
            remark: {
              type: 'string',
              example: '客户信用良好'
            }
          }
        },
        LoanReleaseHistory: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              example: 1
            },
            action: {
              type: 'string',
              enum: ['apply', 'process', 'approve', 'reject', 'complete', 'release'],
              example: 'apply'
            },
            operator: {
              type: 'string',
              example: '刘超'
            },
            time: {
              type: 'string',
              format: 'date-time',
              example: '2025-09-26T03:38:51.000Z'
            },
            comment: {
              type: 'string',
              example: '提交解押申请'
            }
          }
        },
        LoanReleaseCreateRequest: {
          type: 'object',
          required: ['customer_name', 'customer_phone', 'customer_id_card', 'collateral_type', 'release_amount'],
          properties: {
            contract_id: {
              type: 'integer',
              example: 1
            },
            customer_name: {
              type: 'string',
              example: '测试用户'
            },
            customer_phone: {
              type: 'string',
              example: '13800138000'
            },
            customer_id_card: {
              type: 'string',
              example: '511123199001010001'
            },
            farmer_name: {
              type: 'string',
              example: '测试用户'
            },
            product_name: {
              type: 'string',
              example: '测试产品'
            },
            collateral_type: {
              type: 'string',
              enum: ['house', 'car', 'land', 'equipment', 'livestock'],
              example: 'livestock'
            },
            collateral_description: {
              type: 'string',
              example: '测试抵押物'
            },
            collateral_value: {
              type: 'number',
              example: 100000
            },
            loan_amount: {
              type: 'number',
              example: 80000
            },
            release_amount: {
              type: 'number',
              example: 50000
            },
            release_quantity: {
              type: 'string',
              example: '5头'
            },
            application_reason: {
              type: 'string',
              example: '测试解押申请'
            },
            remark: {
              type: 'string',
              example: '测试备注'
            }
          }
        },
        LoanReleaseProcessRequest: {
          type: 'object',
          required: ['action', 'comment'],
          properties: {
            action: {
              type: 'string',
              enum: ['approve', 'reject'],
              example: 'approve'
            },
            comment: {
              type: 'string',
              example: '审核通过'
            },
            remark: {
              type: 'string',
              example: '测试处理'
            }
          }
        }
      },
      responses: {
        UnauthorizedError: {
          description: '未授权访问',
          content: {
            'application/json': {
              schema: {
                $ref: '#/components/schemas/Error'
              },
              example: {
                success: false,
                message: '访问被拒绝，未提供令牌'
              }
            }
          }
        },
        ForbiddenError: {
          description: '权限不足',
          content: {
            'application/json': {
              schema: {
                $ref: '#/components/schemas/Error'
              },
              example: {
                success: false,
                message: '权限不足'
              }
            }
          }
        },
        NotFoundError: {
          description: '资源不存在',
          content: {
            'application/json': {
              schema: {
                $ref: '#/components/schemas/Error'
              },
              example: {
                success: false,
                message: '请求的资源不存在'
              }
            }
          }
        },
        ValidationError: {
          description: '输入数据验证失败',
          content: {
            'application/json': {
              schema: {
                $ref: '#/components/schemas/Error'
              },
              example: {
                success: false,
                message: '输入数据验证失败',
                errors: [
                  {
                    field: 'email',
                    message: '邮箱格式不正确'
                  }
                ]
              }
            }
          }
        },
        InternalServerError: {
          description: '服务器内部错误',
          content: {
            'application/json': {
              schema: {
                $ref: '#/components/schemas/Error'
              },
              example: {
                success: false,
                message: '服务器内部错误'
              }
            }
          }
        }
      }
    },
    security: [
      {
        bearerAuth: []
      }
    ],
    tags: [
      {
        name: 'Authentication',
        description: '认证相关接口'
      },
      {
        name: 'Dashboard',
        description: '仪表盘相关接口'
      },
      {
        name: 'Users',
        description: '用户管理相关接口'
      },
      {
        name: 'Accounts',
        description: '账户管理相关接口'
      },
      {
        name: 'Transactions',
        description: '交易管理相关接口'
      },
      {
        name: 'Loan Products',
        description: '贷款产品管理相关接口'
      },
      {
        name: 'Loan Applications',
        description: '贷款申请管理相关接口'
      },
      {
        name: 'Loan Contracts',
        description: '贷款合同管理相关接口'
      },
      {
        name: 'Loan Release',
        description: '贷款解押管理相关接口'
      },
      {
        name: 'Employees',
        description: '员工管理相关接口'
      },
      {
        name: 'Projects',
        description: '项目管理相关接口'
      },
      {
        name: 'Supervision Tasks',
        description: '监管任务管理相关接口'
      },
      {
        name: 'Installation Tasks',
        description: '安装任务管理相关接口'
      },
      {
        name: 'Completed Supervisions',
        description: '完成监管管理相关接口'
      },
      {
        name: 'Reports',
        description: '报表管理相关接口'
      }
    ]
  },
  apis: [
    './routes/*.js',
    './controllers/*.js'
  ]
};

const specs = swaggerJSDoc(options);

module.exports = specs;