736 lines
20 KiB
JavaScript
736 lines
20 KiB
JavaScript
/**
|
||
* @swagger
|
||
* tags:
|
||
* name: Announcements
|
||
* description: 通知公告管理API
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/{id}:
|
||
* get:
|
||
* summary: 获取单个公告详情
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* responses:
|
||
* 200:
|
||
* description: 成功获取公告详情
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* data:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/{id}/read:
|
||
* post:
|
||
* summary: 标记公告为已读
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* responses:
|
||
* 200:
|
||
* description: 标记已读成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "已标记为已读"
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/unread/count:
|
||
* get:
|
||
* summary: 获取用户未读公告数量
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* responses:
|
||
* 200:
|
||
* description: 获取未读数量成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* data:
|
||
* type: object
|
||
* properties:
|
||
* unread_count:
|
||
* type: integer
|
||
* example: 5
|
||
* description: 未读公告数量
|
||
* 401:
|
||
* description: 未授权
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/batch/read:
|
||
* post:
|
||
* summary: 批量标记公告为已读
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* requestBody:
|
||
* required: true
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* required:
|
||
* - announcement_ids
|
||
* properties:
|
||
* announcement_ids:
|
||
* type: array
|
||
* items:
|
||
* type: integer
|
||
* example: [1, 2, 3]
|
||
* description: 公告ID列表
|
||
* responses:
|
||
* 200:
|
||
* description: 批量标记已读成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "批量标记已读成功"
|
||
* 400:
|
||
* description: 请求参数错误
|
||
* 401:
|
||
* description: 未授权
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements:
|
||
* post:
|
||
* summary: 创建新公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* requestBody:
|
||
* required: true
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* required:
|
||
* - title
|
||
* - content
|
||
* properties:
|
||
* title:
|
||
* type: string
|
||
* description: 公告标题
|
||
* content:
|
||
* type: string
|
||
* description: 公告内容
|
||
* type:
|
||
* type: string
|
||
* enum: [system, maintenance, promotion, warning]
|
||
* default: system
|
||
* priority:
|
||
* type: string
|
||
* enum: [low, medium, high, urgent]
|
||
* default: medium
|
||
* status:
|
||
* type: string
|
||
* enum: [draft, published]
|
||
* default: draft
|
||
* is_pinned:
|
||
* type: boolean
|
||
* default: false
|
||
* publish_time:
|
||
* type: string
|
||
* format: date-time
|
||
* expire_time:
|
||
* type: string
|
||
* format: date-time
|
||
* responses:
|
||
* 201:
|
||
* description: 公告创建成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* message:
|
||
* type: string
|
||
* data:
|
||
* type: object
|
||
* properties:
|
||
* id:
|
||
* type: integer
|
||
* 400:
|
||
* description: 请求参数错误
|
||
* 401:
|
||
* description: 未授权
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/{id}:
|
||
* put:
|
||
* summary: 更新公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* requestBody:
|
||
* required: true
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* title:
|
||
* type: string
|
||
* content:
|
||
* type: string
|
||
* type:
|
||
* type: string
|
||
* enum: [system, maintenance, promotion, warning]
|
||
* priority:
|
||
* type: string
|
||
* enum: [low, medium, high, urgent]
|
||
* status:
|
||
* type: string
|
||
* enum: [draft, published, archived]
|
||
* is_pinned:
|
||
* type: boolean
|
||
* publish_time:
|
||
* type: string
|
||
* format: date-time
|
||
* expire_time:
|
||
* type: string
|
||
* format: date-time
|
||
* responses:
|
||
* 200:
|
||
* description: 公告更新成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* message:
|
||
* type: string
|
||
* data:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* 400:
|
||
* description: 请求参数错误
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*
|
||
* delete:
|
||
* summary: 删除公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* responses:
|
||
* 200:
|
||
* description: 公告删除成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* message:
|
||
* type: string
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/public/list:
|
||
* get:
|
||
* summary: 获取公开发布的公告列表（无需认证）
|
||
* tags: [Announcements]
|
||
* parameters:
|
||
* - in: query
|
||
* name: limit
|
||
* schema:
|
||
* type: integer
|
||
* default: 5
|
||
* description: 获取数量
|
||
* responses:
|
||
* 200:
|
||
* description: 成功获取公开公告列表
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* data:
|
||
* type: array
|
||
* items:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* components:
|
||
* schemas:
|
||
* Announcement:
|
||
* type: object
|
||
* required:
|
||
* - title
|
||
* - content
|
||
* properties:
|
||
* id:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* title:
|
||
* type: string
|
||
* description: 公告标题
|
||
* content:
|
||
* type: string
|
||
* description: 公告内容
|
||
* type:
|
||
* type: string
|
||
* description: 公告类型
|
||
* enum: [system, maintenance, promotion, warning]
|
||
* priority:
|
||
* type: string
|
||
* description: 优先级
|
||
* enum: [low, medium, high, urgent]
|
||
* status:
|
||
* type: string
|
||
* description: 状态
|
||
* enum: [draft, published, archived]
|
||
* is_pinned:
|
||
* type: boolean
|
||
* description: 是否置顶
|
||
* publish_time:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 发布时间
|
||
* expire_time:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 过期时间
|
||
* created_by:
|
||
* type: integer
|
||
* description: 创建者ID
|
||
* created_at:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 创建时间
|
||
* updated_at:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 更新时间
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements:
|
||
* get:
|
||
* summary: 获取通知公告列表
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: query
|
||
* name: page
|
||
* schema:
|
||
* type: integer
|
||
* default: 1
|
||
* description: 页码
|
||
* - in: query
|
||
* name: limit
|
||
* schema:
|
||
* type: integer
|
||
* default: 10
|
||
* description: 每页数量
|
||
* - in: query
|
||
* name: search
|
||
* schema:
|
||
* type: string
|
||
* description: 搜索关键词（标题或内容）
|
||
* - in: query
|
||
* name: type
|
||
* schema:
|
||
* type: string
|
||
* enum: [system, activity, maintenance, urgent]
|
||
* description: 公告类型
|
||
* - in: query
|
||
* name: priority
|
||
* schema:
|
||
* type: string
|
||
* enum: [high, medium, low]
|
||
* description: 优先级
|
||
* - in: query
|
||
* name: status
|
||
* schema:
|
||
* type: string
|
||
* enum: [draft, published, expired]
|
||
* description: 状态
|
||
* - in: query
|
||
* name: isTop
|
||
* schema:
|
||
* type: boolean
|
||
* description: 是否置顶
|
||
* - in: query
|
||
* name: sortBy
|
||
* schema:
|
||
* type: string
|
||
* enum: [created_at, updated_at, publish_time, priority]
|
||
* default: created_at
|
||
* description: 排序字段
|
||
* - in: query
|
||
* name: sortOrder
|
||
* schema:
|
||
* type: string
|
||
* enum: [ASC, DESC]
|
||
* default: DESC
|
||
* description: 排序方向
|
||
* responses:
|
||
* 200:
|
||
* description: 成功获取公告列表
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* data:
|
||
* type: object
|
||
* properties:
|
||
* announcements:
|
||
* type: array
|
||
* items:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* total:
|
||
* type: integer
|
||
* example: 50
|
||
* page:
|
||
* type: integer
|
||
* example: 1
|
||
* limit:
|
||
* type: integer
|
||
* example: 10
|
||
* totalPages:
|
||
* type: integer
|
||
* example: 5
|
||
* 401:
|
||
* description: 未授权
|
||
* 500:
|
||
* description: 服务器错误
|
||
*
|
||
* post:
|
||
* summary: 创建新的通知公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* requestBody:
|
||
* required: true
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* required:
|
||
* - title
|
||
* - content
|
||
* - type
|
||
* - priority
|
||
* properties:
|
||
* title:
|
||
* type: string
|
||
* description: 公告标题
|
||
* example: "系统维护通知"
|
||
* content:
|
||
* type: string
|
||
* description: 公告内容
|
||
* example: "系统将于今晚进行维护，预计维护时间2小时"
|
||
* type:
|
||
* type: string
|
||
* enum: [system, activity, maintenance, urgent]
|
||
* description: 公告类型
|
||
* example: "maintenance"
|
||
* priority:
|
||
* type: string
|
||
* enum: [high, medium, low]
|
||
* description: 优先级
|
||
* example: "high"
|
||
* status:
|
||
* type: string
|
||
* enum: [draft, published]
|
||
* default: draft
|
||
* description: 状态
|
||
* isTop:
|
||
* type: boolean
|
||
* default: false
|
||
* description: 是否置顶
|
||
* publishTime:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 发布时间
|
||
* expireTime:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 过期时间
|
||
* responses:
|
||
* 201:
|
||
* description: 公告创建成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "公告创建成功"
|
||
* data:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* 400:
|
||
* description: 请求参数错误
|
||
* 401:
|
||
* description: 未授权
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/{id}:
|
||
* put:
|
||
* summary: 更新通知公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* requestBody:
|
||
* required: true
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* title:
|
||
* type: string
|
||
* description: 公告标题
|
||
* content:
|
||
* type: string
|
||
* description: 公告内容
|
||
* type:
|
||
* type: string
|
||
* enum: [system, activity, maintenance, urgent]
|
||
* description: 公告类型
|
||
* priority:
|
||
* type: string
|
||
* enum: [high, medium, low]
|
||
* description: 优先级
|
||
* status:
|
||
* type: string
|
||
* enum: [draft, published, expired]
|
||
* description: 状态
|
||
* isTop:
|
||
* type: boolean
|
||
* description: 是否置顶
|
||
* publishTime:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 发布时间
|
||
* expireTime:
|
||
* type: string
|
||
* format: date-time
|
||
* description: 过期时间
|
||
* responses:
|
||
* 200:
|
||
* description: 公告更新成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "公告更新成功"
|
||
* data:
|
||
* $ref: '#/components/schemas/Announcement'
|
||
* 400:
|
||
* description: 请求参数错误
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*
|
||
* delete:
|
||
* summary: 删除通知公告
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* responses:
|
||
* 200:
|
||
* description: 公告删除成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "公告删除成功"
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/
|
||
|
||
/**
|
||
* @swagger
|
||
* /api/announcements/{id}/toggle-top:
|
||
* put:
|
||
* summary: 切换公告置顶状态
|
||
* tags: [Announcements]
|
||
* security:
|
||
* - bearerAuth: []
|
||
* parameters:
|
||
* - in: path
|
||
* name: id
|
||
* required: true
|
||
* schema:
|
||
* type: integer
|
||
* description: 公告ID
|
||
* responses:
|
||
* 200:
|
||
* description: 置顶状态切换成功
|
||
* content:
|
||
* application/json:
|
||
* schema:
|
||
* type: object
|
||
* properties:
|
||
* success:
|
||
* type: boolean
|
||
* example: true
|
||
* message:
|
||
* type: string
|
||
* example: "置顶状态更新成功"
|
||
* data:
|
||
* type: object
|
||
* properties:
|
||
* isTop:
|
||
* type: boolean
|
||
* example: true
|
||
* 401:
|
||
* description: 未授权
|
||
* 404:
|
||
* description: 公告不存在
|
||
* 500:
|
||
* description: 服务器错误
|
||
*/ |