216 lines
4.9 KiB
JavaScript
216 lines
4.9 KiB
JavaScript
/**
|
|
* Swagger API文档配置
|
|
* @file swagger.js
|
|
* @description API文档配置和定义
|
|
*/
|
|
const swaggerJSDoc = require('swagger-jsdoc');
|
|
|
|
const options = {
|
|
definition: {
|
|
openapi: '3.0.0',
|
|
info: {
|
|
title: '银行管理后台API',
|
|
version: '1.0.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
|
|
}
|
|
}
|
|
}
|
|
},
|
|
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: 'Users',
|
|
description: '用户管理相关接口'
|
|
},
|
|
{
|
|
name: 'Accounts',
|
|
description: '账户管理相关接口'
|
|
},
|
|
{
|
|
name: 'Transactions',
|
|
description: '交易管理相关接口'
|
|
}
|
|
]
|
|
},
|
|
apis: [
|
|
'./routes/*.js',
|
|
'./controllers/*.js'
|
|
]
|
|
};
|
|
|
|
const specs = swaggerJSDoc(options);
|
|
|
|
module.exports = specs; |