445 lines
18 KiB
TypeScript
445 lines
18 KiB
TypeScript
/**
|
||
* @file Swagger插件封装
|
||
* @author hotok
|
||
* @date 2025-06-28
|
||
* @lastEditor hotok
|
||
* @lastEditTime 2025-06-28
|
||
* @description 封装Elysia Swagger插件，统一管理API文档配置，包含全局响应示例和错误码说明
|
||
*/
|
||
|
||
import { swagger } from '@elysiajs/swagger';
|
||
|
||
/**
|
||
* Swagger插件实例
|
||
* @description 统一API文档配置，包含全局响应组件、错误码说明等
|
||
*/
|
||
export const swaggerPlugin = swagger({
|
||
path: '/docs',
|
||
documentation: {
|
||
info: {
|
||
title: 'Cursor Init API服务',
|
||
version: '1.0.0',
|
||
description: `
|
||
# Cursor Init API服务
|
||
|
||
基于 **Elysia + Bun.js** 构建的高性能API服务，集成以下功能：
|
||
|
||
## 🚀 核心特性
|
||
|
||
- **JWT认证**: 完整的用户认证和授权体系
|
||
- **MySQL数据库**: 数据持久化和高性能查询
|
||
- **Redis缓存**: 分布式缓存和会话管理
|
||
- **Winston日志**: 结构化日志记录和监控
|
||
- **健康检查**: 系统和依赖服务状态监控
|
||
- **统一响应**: 标准化的API响应格式
|
||
- **参数验证**: 严格的输入参数校验
|
||
- **错误处理**: 全局异常捕获和友好错误信息
|
||
|
||
## 📋 错误码说明
|
||
|
||
| 错误码 | 说明 | 示例场景 |
|
||
|--------|------|----------|
|
||
| 0 | 操作成功 | 正常业务流程 |
|
||
| 400 | 业务逻辑错误 | 用户名已存在、余额不足等 |
|
||
| 401 | 身份认证失败 | Token无效、未登录等 |
|
||
| 403 | 权限不足 | 无操作权限、角色限制等 |
|
||
| 404 | 资源未找到 | 用户不存在、页面不存在等 |
|
||
| 422 | 参数验证失败 | 邮箱格式错误、必填参数缺失等 |
|
||
| 500 | 服务器内部错误 | 数据库异常、系统故障等 |
|
||
| 503 | 服务不可用 | 系统维护、依赖服务异常等 |
|
||
|
||
## 🔐 认证说明
|
||
|
||
大部分接口需要JWT认证，请在请求头中添加：
|
||
\`\`\`
|
||
Authorization: Bearer <your-jwt-token>
|
||
\`\`\`
|
||
|
||
## 📝 响应格式
|
||
|
||
所有API响应均采用统一格式：
|
||
\`\`\`json
|
||
{
|
||
"code": 0,
|
||
"message": "操作成功",
|
||
"data": {
|
||
// 具体数据
|
||
}
|
||
}
|
||
\`\`\`
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [健康检查](/api/health) - 系统健康状态
|
||
- [详细健康检查](/api/health/detailed) - 包含性能指标的详细状态
|
||
`,
|
||
contact: {
|
||
name: 'API支持',
|
||
email: 'support@example.com',
|
||
url: 'https://github.com/your-org/cursor-init',
|
||
},
|
||
license: {
|
||
name: 'MIT',
|
||
url: 'https://opensource.org/licenses/MIT',
|
||
},
|
||
termsOfService: 'https://example.com/terms',
|
||
},
|
||
servers: [
|
||
{
|
||
url: 'http://localhost:3000',
|
||
description: '开发环境',
|
||
},
|
||
{
|
||
url: 'https://api.example.com',
|
||
description: '生产环境',
|
||
},
|
||
],
|
||
components: {
|
||
securitySchemes: {
|
||
bearerAuth: {
|
||
type: 'http',
|
||
scheme: 'bearer',
|
||
bearerFormat: 'JWT',
|
||
description: `
|
||
JWT认证说明：
|
||
|
||
1. 通过登录接口获取JWT token
|
||
2. 在需要认证的接口请求头中添加：Authorization: Bearer <token>
|
||
3. Token有效期为24小时，过期后需重新登录
|
||
4. Token格式：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
|
||
**示例：**
|
||
\`\`\`
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
||
\`\`\`
|
||
`,
|
||
},
|
||
},
|
||
schemas: {
|
||
BaseResponse: {
|
||
type: 'object',
|
||
description: '基础响应结构',
|
||
required: ['code', 'message', 'data'],
|
||
properties: {
|
||
code: {
|
||
type: 'number',
|
||
description: '响应码，0表示成功，其他表示错误',
|
||
example: 0,
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
description: '响应消息，描述操作结果',
|
||
example: '操作成功',
|
||
},
|
||
data: {
|
||
description: '响应数据，成功时包含具体数据，失败时通常为null',
|
||
},
|
||
},
|
||
},
|
||
SuccessResponse: {
|
||
type: 'object',
|
||
description: '成功响应',
|
||
required: ['code', 'message', 'data'],
|
||
properties: {
|
||
code: {
|
||
type: 'number',
|
||
enum: [0],
|
||
description: '成功响应码',
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
description: '成功消息',
|
||
example: '操作成功',
|
||
},
|
||
data: {
|
||
description: '成功时返回的数据',
|
||
},
|
||
},
|
||
},
|
||
ErrorResponse: {
|
||
type: 'object',
|
||
description: '错误响应',
|
||
required: ['code', 'message', 'data'],
|
||
properties: {
|
||
code: {
|
||
type: 'number',
|
||
description: '错误响应码',
|
||
example: 400,
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
description: '错误消息',
|
||
example: '参数验证失败',
|
||
},
|
||
data: {
|
||
type: 'null',
|
||
description: '错误时数据字段为null',
|
||
},
|
||
},
|
||
},
|
||
PaginationResponse: {
|
||
type: 'object',
|
||
description: '分页响应',
|
||
required: ['code', 'message', 'data'],
|
||
properties: {
|
||
code: {
|
||
type: 'number',
|
||
enum: [0],
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
},
|
||
data: {
|
||
type: 'object',
|
||
required: ['list', 'pagination'],
|
||
properties: {
|
||
list: {
|
||
type: 'array',
|
||
description: '数据列表',
|
||
items: {},
|
||
},
|
||
pagination: {
|
||
type: 'object',
|
||
description: '分页信息',
|
||
required: ['page', 'pageSize', 'total', 'totalPages', 'hasNext', 'hasPrev'],
|
||
properties: {
|
||
page: {
|
||
type: 'number',
|
||
description: '当前页码，从1开始',
|
||
minimum: 1,
|
||
examples: [1, 2, 3],
|
||
},
|
||
pageSize: {
|
||
type: 'number',
|
||
description: '每页条数',
|
||
minimum: 1,
|
||
maximum: 100,
|
||
examples: [10, 20, 50],
|
||
},
|
||
total: {
|
||
type: 'number',
|
||
description: '总条数',
|
||
minimum: 0,
|
||
examples: [0, 100, 1500],
|
||
},
|
||
totalPages: {
|
||
type: 'number',
|
||
description: '总页数',
|
||
minimum: 0,
|
||
examples: [0, 5, 75],
|
||
},
|
||
hasNext: {
|
||
type: 'boolean',
|
||
description: '是否有下一页',
|
||
},
|
||
hasPrev: {
|
||
type: 'boolean',
|
||
description: '是否有上一页',
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
responses: {
|
||
Success: {
|
||
description: '操作成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/SuccessResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '成功示例',
|
||
value: {
|
||
code: 0,
|
||
message: '操作成功',
|
||
data: {
|
||
id: 1,
|
||
name: '示例数据',
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
BadRequest: {
|
||
description: '业务逻辑错误',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '业务错误示例',
|
||
value: {
|
||
code: 400,
|
||
message: '用户名已存在',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
Unauthorized: {
|
||
description: '身份认证失败',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
tokenExpired: {
|
||
summary: 'Token过期',
|
||
value: {
|
||
code: 401,
|
||
message: 'Token已过期，请重新登录',
|
||
data: null,
|
||
},
|
||
},
|
||
tokenInvalid: {
|
||
summary: 'Token无效',
|
||
value: {
|
||
code: 401,
|
||
message: 'Token格式错误或无效',
|
||
data: null,
|
||
},
|
||
},
|
||
notLoggedIn: {
|
||
summary: '未登录',
|
||
value: {
|
||
code: 401,
|
||
message: '请先登录',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
Forbidden: {
|
||
description: '权限不足',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '权限不足示例',
|
||
value: {
|
||
code: 403,
|
||
message: '权限不足，无法访问该资源',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
NotFound: {
|
||
description: '资源未找到',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '资源不存在示例',
|
||
value: {
|
||
code: 404,
|
||
message: '请求的资源不存在',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
ValidationError: {
|
||
description: '参数验证失败',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '参数验证失败示例',
|
||
value: {
|
||
code: 422,
|
||
message: '邮箱格式不正确',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
InternalError: {
|
||
description: '服务器内部错误',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '服务器错误示例',
|
||
value: {
|
||
code: 500,
|
||
message: '服务器内部错误，请稍后重试',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
ServiceUnavailable: {
|
||
description: '服务不可用',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/ErrorResponse',
|
||
},
|
||
examples: {
|
||
default: {
|
||
summary: '服务不可用示例',
|
||
value: {
|
||
code: 503,
|
||
message: '服务暂时不可用，请稍后重试',
|
||
data: null,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
security: [{ bearerAuth: [] }],
|
||
tags: [
|
||
{
|
||
name: '认证管理',
|
||
description: '用户认证相关接口，包括登录、注册、Token验证等',
|
||
},
|
||
{
|
||
name: '用户管理',
|
||
description: '用户信息管理接口',
|
||
},
|
||
{
|
||
name: '健康检查',
|
||
description: '系统健康状态监控接口',
|
||
},
|
||
],
|
||
},
|
||
});
|