docs: 更新项目文档，完善需求和技术细节
This commit is contained in:
ylweng
@@ -1,15 +1,16 @@
|
||||
const swaggerJsdoc = require('swagger-jsdoc');
|
||||
const swaggerJSDoc = require('swagger-jsdoc');
|
||||
const swaggerUi = require('swagger-ui-express');
|
||||
|
||||
// Swagger 配置选项
|
||||
const options = {
|
||||
definition: {
|
||||
openapi: '3.0.0',
|
||||
info: {
|
||||
title: '爱鉴花小程序后端API',
|
||||
title: '爱鉴花 API 文档',
|
||||
version: '1.0.0',
|
||||
description: '爱鉴花小程序后端RESTful API文档',
|
||||
description: '爱鉴花小程序和后端管理系统的 RESTful API 文档',
|
||||
contact: {
|
||||
name: 'API支持',
|
||||
name: '技术支持',
|
||||
email: 'support@aijianhua.com'
|
||||
},
|
||||
license: {
|
||||
@@ -19,15 +20,17 @@ const options = {
|
||||
},
|
||||
servers: [
|
||||
{
|
||||
url: process.env.NODE_ENV === 'production'
|
||||
? 'https://api.aijianhua.com'
|
||||
: `http://localhost:${process.env.PORT || 3200}`,
|
||||
description: process.env.NODE_ENV === 'production' ? '生产环境' : '开发环境'
|
||||
url: 'http://localhost:3200/api/v1',
|
||||
description: '开发环境'
|
||||
},
|
||||
{
|
||||
url: 'https://api.aijianhua.com/api/v1',
|
||||
description: '生产环境'
|
||||
}
|
||||
],
|
||||
components: {
|
||||
securitySchemes: {
|
||||
BearerAuth: {
|
||||
bearerAuth: {
|
||||
type: 'http',
|
||||
scheme: 'bearer',
|
||||
bearerFormat: 'JWT'
|
||||
@@ -37,117 +40,286 @@ const options = {
|
||||
User: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer', example: 1 },
|
||||
username: { type: 'string', example: 'testuser' },
|
||||
phone: { type: 'string', example: '13800138000' },
|
||||
email: { type: 'string', example: 'user@example.com' },
|
||||
user_type: { type: 'string', enum: ['farmer', 'buyer', 'admin'], example: 'farmer' },
|
||||
avatar_url: { type: 'string', example: '/uploads/avatars/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' }
|
||||
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 },
|
||||
price: { type: 'number', format: 'float', example: 29.9 },
|
||||
stock: { type: 'integer', example: 100 },
|
||||
image: { type: 'string', example: '/uploads/products/rose.jpg' },
|
||||
description: { type: 'string', example: '新鲜玫瑰花，香气浓郁' },
|
||||
status: { type: 'integer', enum: [0, 1], 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' }
|
||||
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: 'O123456789' },
|
||||
user_id: { type: 'integer', example: 1 },
|
||||
total_amount: { type: 'number', format: 'float', example: 99.9 },
|
||||
payment_status: { type: 'string', enum: ['pending', 'paid', 'cancelled'], example: 'pending' },
|
||||
shipping_status: { type: 'string', enum: ['pending', 'shipped', 'delivered'], example: 'pending' },
|
||||
shipping_address: { type: 'string', example: '北京市朝阳区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' }
|
||||
}
|
||||
},
|
||||
Identification: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer', example: 1 },
|
||||
user_id: { type: 'integer', example: 1 },
|
||||
image_url: { type: 'string', example: '/uploads/identifications/identify-123.jpg' },
|
||||
result: { type: 'string', description: 'JSON格式的识别结果' },
|
||||
confidence: { type: 'number', format: 'float', example: 0.95 },
|
||||
created_at: { type: 'string', format: 'date-time', example: '2023-01-01T00:00:00Z' }
|
||||
}
|
||||
},
|
||||
Error: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
code: { type: 'integer', example: 400 },
|
||||
message: { type: 'string', example: '参数验证失败' },
|
||||
data: { type: 'object', nullable: true, example: null }
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
UnauthorizedError: {
|
||||
description: '未授权访问',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/Error' },
|
||||
example: {
|
||||
code: 401,
|
||||
message: '未提供有效的认证token',
|
||||
data: null
|
||||
}
|
||||
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'
|
||||
}
|
||||
}
|
||||
},
|
||||
NotFoundError: {
|
||||
description: '资源不存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/Error' },
|
||||
example: {
|
||||
code: 404,
|
||||
message: '资源不存在',
|
||||
data: null
|
||||
}
|
||||
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
|
||||
}
|
||||
}
|
||||
},
|
||||
ValidationError: {
|
||||
description: '参数验证失败',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/Error' },
|
||||
example: {
|
||||
code: 400,
|
||||
message: '参数验证失败',
|
||||
data: null
|
||||
}
|
||||
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: [] }
|
||||
{
|
||||
bearerAuth: []
|
||||
}
|
||||
]
|
||||
},
|
||||
apis: [
|
||||
'./routes/*.js',
|
||||
'./middlewares/*.js'
|
||||
]
|
||||
apis: ['./routes/*.js'] // 扫描路由文件中的 Swagger 注释
|
||||
};
|
||||
|
||||
const specs = swaggerJsdoc(options);
|
||||
const specs = swaggerJSDoc(options);
|
||||
|
||||
module.exports = { specs, swaggerUi };
|
||||
Reference in New Issue
Block a user