Generating commit message...
This commit is contained in:
298
backend/src/docs/swagger.js
Normal file
298
backend/src/docs/swagger.js
Normal file
@@ -0,0 +1,298 @@
|
||||
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: '结伴客系统 - 旅行结伴与动物认领平台',
|
||||
contact: {
|
||||
name: '技术支持',
|
||||
email: 'support@jiebanke.com',
|
||||
url: 'https://www.jiebanke.com'
|
||||
},
|
||||
license: {
|
||||
name: 'MIT',
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
}
|
||||
},
|
||||
servers: [
|
||||
{
|
||||
url: 'http://localhost:3000/api/v1',
|
||||
description: '开发环境'
|
||||
},
|
||||
{
|
||||
url: 'https://api.jiebanke.com/api/v1',
|
||||
description: '生产环境'
|
||||
}
|
||||
],
|
||||
components: {
|
||||
securitySchemes: {
|
||||
BearerAuth: {
|
||||
type: 'http',
|
||||
scheme: 'bearer',
|
||||
bearerFormat: 'JWT'
|
||||
}
|
||||
},
|
||||
schemas: {
|
||||
// 通用响应模型
|
||||
ApiResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: {
|
||||
type: 'boolean',
|
||||
description: '请求是否成功'
|
||||
},
|
||||
code: {
|
||||
type: 'integer',
|
||||
description: '状态码'
|
||||
},
|
||||
message: {
|
||||
type: 'string',
|
||||
description: '消息描述'
|
||||
},
|
||||
data: {
|
||||
type: 'object',
|
||||
description: '业务数据'
|
||||
},
|
||||
timestamp: {
|
||||
type: 'string',
|
||||
format: 'date-time',
|
||||
description: '响应时间戳'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 错误响应模型
|
||||
ErrorResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: {
|
||||
type: 'boolean',
|
||||
example: false
|
||||
},
|
||||
code: {
|
||||
type: 'integer',
|
||||
example: 400
|
||||
},
|
||||
message: {
|
||||
type: 'string',
|
||||
example: '请求参数错误'
|
||||
},
|
||||
error: {
|
||||
type: 'string',
|
||||
example: '详细错误信息'
|
||||
},
|
||||
timestamp: {
|
||||
type: 'string',
|
||||
format: 'date-time'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 用户模型
|
||||
User: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: {
|
||||
type: 'integer',
|
||||
example: 1
|
||||
},
|
||||
username: {
|
||||
type: 'string',
|
||||
example: 'testuser'
|
||||
},
|
||||
nickname: {
|
||||
type: '极速版string',
|
||||
example: '测试用户'
|
||||
},
|
||||
email: {
|
||||
type: 'string',
|
||||
example: 'test@example.com'
|
||||
},
|
||||
phone: {
|
||||
type: 'string',
|
||||
example: '13800138000'
|
||||
},
|
||||
avatar: {
|
||||
type: 'string',
|
||||
example: 'https://example.com/avatar.jpg'
|
||||
},
|
||||
gender: {
|
||||
type: 'string',
|
||||
enum: ['male', 'female', 'unknown'],
|
||||
example: 'male'
|
||||
},
|
||||
birthday: {
|
||||
type: 'string',
|
||||
format: 'date',
|
||||
example: '1990-01-01'
|
||||
},
|
||||
points: {
|
||||
type: 'integer',
|
||||
example: 1000
|
||||
},
|
||||
level: {
|
||||
type: 'integer',
|
||||
example: 3
|
||||
},
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['active', 'inactive', 'banned'],
|
||||
example: 'active'
|
||||
},
|
||||
created_at: {
|
||||
type: 'string',
|
||||
format: 'date-time'
|
||||
},
|
||||
updated_at: {
|
||||
type: 'string',
|
||||
format: 'date-time'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 分页模型
|
||||
Pagination: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
total: {
|
||||
type: 'integer',
|
||||
example: 100
|
||||
},
|
||||
page: {
|
||||
type: 'integer',
|
||||
example: 1
|
||||
},
|
||||
pageSize: {
|
||||
type: 'integer',
|
||||
example: 20
|
||||
},
|
||||
totalPages: {
|
||||
type: 'integer',
|
||||
example: 5
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
parameters: {
|
||||
// 通用分页参数
|
||||
PageParam: {
|
||||
in: 'query',
|
||||
name: 'page',
|
||||
schema: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
default: 1
|
||||
},
|
||||
description: '页码'
|
||||
},
|
||||
PageSizeParam: {
|
||||
in: 'query',
|
||||
name: 'pageSize',
|
||||
schema: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
maximum: 100,
|
||||
default: 20
|
||||
},
|
||||
description: '每页数量'
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
// 通用响应
|
||||
UnauthorizedError: {
|
||||
description: '未授权访问',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 401,
|
||||
message: '未授权访问',
|
||||
error: 'Token已过期或无效',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
ForbiddenError: {
|
||||
description: '禁止访问',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 403,
|
||||
message: '禁止访问',
|
||||
error: '权限不足',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
NotFoundError: {
|
||||
description: '资源不存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 404,
|
||||
message: '资源不存在',
|
||||
error: '请求的资源不存在',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
ValidationError: {
|
||||
description: '参数验证错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 400,
|
||||
message: '参数验证错误',
|
||||
error: '用户名必须为4-20个字符',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
security: [
|
||||
{
|
||||
BearerAuth: []
|
||||
}
|
||||
]
|
||||
},
|
||||
apis: [
|
||||
'./src/routes/*.js',
|
||||
'./src/controllers/*.js',
|
||||
'./src/models/*.js'
|
||||
]
|
||||
};
|
||||
|
||||
const specs = swaggerJsdoc(options);
|
||||
|
||||
module.exports = {
|
||||
swaggerUi,
|
||||
specs,
|
||||
serve: swaggerUi.serve,
|
||||
setup: swaggerUi.setup(specs, {
|
||||
explorer: true,
|
||||
customCss: '.swagger-ui .topbar { display: none }',
|
||||
customSiteTitle: '结伴客系统 API文档'
|
||||
})
|
||||
};
|
||||
Reference in New Issue
Block a user