AI_OJ/aioj-backend-blog-service/接口文档.md

AIOJ 博客服务接口文档

服务信息

• 服务名称: aioj-blog-service
• 服务端口: 18086
• 基础路径: /api
• API 文档: /swagger-ui.html

通用说明

统一响应格式

所有接口均使用统一的响应格式 Result<T>：

{
  "code": "0",        // 响应码，"0"表示成功
  "message": "success", // 响应信息
  "data": {}          // 响应数据
}

分页响应格式

分页查询返回 IPage<T> 格式：

{
  "code": "0",
  "message": "success",
  "data": {
    "records": [],    // 数据列表
    "total": 100,     // 总记录数
    "size": 10,       // 每页数量
    "current": 1,     // 当前页码
    "pages": 10       // 总页数
  }
}

---

1. 文章管理接口

1.1 创建文章

• 接口: POST /api/v1/article/create
• 描述: 创建新文章，支持 Markdown 格式

请求参数:

字段	类型	必填	说明	示例
title	String	是	文章标题	Spring Boot 3.5.7 新特性详解
slug	String	否	文章别名（URL友好标识）	spring-boot-3-5-7-features
summary	String	否	文章摘要	本文详细介绍Spring Boot 3.5.7版本的新特性...
content	String	是	文章内容（Markdown格式）	# 欢迎使用...
coverImage	String	否	封面图片URL	https://example.com/images/cover.jpg
categoryId	Long	是	分类ID	1
tagIds	List<Long>	否	标签ID列表	[1, 2, 3]
isTop	Integer	否	是否置顶（0=否，1=是）	0
isEssence	Integer	否	是否精华（0=否，1=是）	0
isPublished	Integer	否	是否发布（0=草稿，1=已发布）	1

响应示例:

{
  "code": "0",
  "message": "success",
  "data": 123
}

1.2 更新文章

• 接口: PUT /api/v1/article/update
• 描述: 更新已存在的文章信息

请求参数:

字段	类型	必填	说明
id	Long	是	文章ID
其他字段	-	-	同创建文章

1.3 删除文章

• 接口: DELETE /api/v1/article/delete/{articleId}
• 描述: 逻辑删除指定文章

路径参数:

参数	类型	必填	说明
articleId	Long	是	文章ID

1.4 查询文章详情

• 接口: GET /api/v1/article/{articleId}
• 描述: 根据文章ID查询文章详细信息

响应示例:

{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "title": "Spring Boot 3.5.7 新特性详解",
    "slug": "spring-boot-3-5-7-features",
    "summary": "本文详细介绍Spring Boot 3.5.7版本的新特性...",
    "content": "# 欢迎使用...",
    "contentHtml": "<h1>欢迎使用...</h1>",
    "coverImage": "https://example.com/images/cover.jpg",
    "authorId": 1,
    "authorName": "admin",
    "categoryId": 1,
    "categoryName": "算法题解",
    "tags": [
      {
        "id": 1,
        "name": "数据结构",
        "slug": "data-structure",
        "color": "#3498db"
      }
    ],
    "viewCount": 100,
    "likeCount": 10,
    "commentCount": 5,
    "collectCount": 3,
    "isTop": 0,
    "isEssence": 0,
    "isPublished": 1,
    "status": 1,
    "publishTime": "2026-01-26T10:00:00",
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T10:00:00",
    "isLiked": false,
    "isCollected": false
  }
}

1.5 根据slug查询文章

• 接口: GET /api/v1/article/slug/{slug}

1.6 分页查询文章列表

• 接口: POST /api/v1/article/list

请求参数:

字段	类型	必填	说明
current	Integer	否	页码，默认1
size	Integer	否	每页数量，默认10
id	Long	否	文章ID
title	String	否	文章标题（模糊查询）
categoryId	Long	否	分类ID
tagId	Long	否	标签ID
authorId	Long	否	作者ID
isTop	Integer	否	是否置顶
isEssence	Integer	否	是否精华
isPublished	Integer	否	是否发布（0=草稿，1=已发布）
status	Integer	否	文章状态（1=正常，2=审核中，3=已关闭，4=已删除）
sortField	String	否	排序字段（view_count/like_count/comment_count/publish_time）
sortOrder	String	否	排序方式（asc/desc）

1.7 发布文章

• 接口: PUT /api/v1/article/publish/{articleId}

1.8 取消发布文章

• 接口: PUT /api/v1/article/unpublish/{articleId}

1.9 增加文章浏览量

• 接口: POST /api/v1/article/view/{articleId}

---

2. 分类管理接口

2.1 创建分类

• 接口: POST /api/v1/category/create

请求参数:

字段	类型	必填	说明
name	String	是	分类名称
slug	String	否	分类别名
description	String	否	分类描述
icon	String	否	分类图标
sortOrder	Integer	否	排序序号
parentId	Long	否	父分类ID
isEnabled	Integer	否	是否启用

2.2 更新分类

• 接口: PUT /api/v1/category/update

2.3 删除分类

• 接口: DELETE /api/v1/category/delete/{categoryId}

2.4 查询分类详情

• 接口: GET /api/v1/category/{categoryId}

响应示例:

{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "name": "算法题解",
    "slug": "algorithm-solutions",
    "description": "算法题目解题思路和代码分享",
    "icon": "💡",
    "sortOrder": 1,
    "parentId": 0,
    "articleCount": 10,
    "isEnabled": 1,
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T09:00:00"
  }
}

2.5 根据slug查询分类

• 接口: GET /api/v1/category/slug/{slug}

2.6 查询所有分类

• 接口: GET /api/v1/category/list/all

2.7 查询启用的分类

• 接口: GET /api/v1/category/list/enabled

---

3. 标签管理接口

3.1 创建标签

• 接口: POST /api/v1/tag/create

请求参数:

字段	类型	必填	说明
name	String	是	标签名称
slug	String	否	标签别名
description	String	否	标签描述
color	String	否	标签颜色
isEnabled	Integer	否	是否启用

3.2 更新标签

• 接口: PUT /api/v1/tag/update

3.3 删除标签

• 接口: DELETE /api/v1/tag/delete/{tagId}

3.4 查询标签详情

• 接口: GET /api/v1/tag/{tagId}

响应示例:

{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "name": "数据结构",
    "slug": "data-structure",
    "description": "数据结构与算法相关内容",
    "color": "#3498db",
    "articleCount": 5,
    "isEnabled": 1,
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T09:00:00"
  }
}

3.5 根据slug查询标签

• 接口: GET /api/v1/tag/slug/{slug}

3.6 查询所有标签

• 接口: GET /api/v1/tag/list/all

3.7 查询启用的标签

• 接口: GET /api/v1/tag/list/enabled

3.8 查询文章的标签

• 接口: GET /api/v1/tag/article/{articleId}

---

4. 评论管理接口

4.1 发表评论

• 接口: POST /api/v1/comment/create

请求参数:

字段	类型	必填	说明
articleId	Long	是	文章ID
content	String	是	评论内容（支持Markdown）
parentId	Long	否	父评论ID（0表示一级评论）
replyToId	Long	否	回复的评论ID（用于@提醒）

4.2 回复评论

• 接口: POST /api/v1/comment/reply

4.3 删除评论

• 接口: DELETE /api/v1/comment/delete/{commentId}

4.4 查询评论详情

• 接口: GET /api/v1/comment/{commentId}

响应示例:

{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "articleId": 1,
    "userId": 1,
    "userName": "admin",
    "userAvatar": "https://example.com/avatar.jpg",
    "parentId": 0,
    "replyToId": 0,
    "replyToName": null,
    "content": "这篇文章写得很好！",
    "contentHtml": "<p>这篇文章写得很好！</p>",
    "likeCount": 5,
    "replyCount": 2,
    "isAuthor": 1,
    "status": 1,
    "createTime": "2026-01-26T10:00:00",
    "updateTime": "2026-01-26T10:00:00",
    "isLiked": false,
    "children": []
  }
}

4.5 查询文章评论

• 接口: GET /api/v1/comment/article/{articleId}
• 描述: 根据文章ID查询该文章的所有评论（树形结构）

4.6 分页查询评论列表

• 接口: POST /api/v1/comment/list

4.7 查询子评论

• 接口: GET /api/v1/comment/children/{parentId}

---

5. 点赞管理接口

5.1 点赞

• 接口: POST /api/v1/like/like

请求参数:

字段	类型	必填	说明
targetId	Long	是	目标ID
targetType	Integer	是	目标类型（1=文章，2=评论）

5.2 取消点赞

• 接口: POST /api/v1/like/unlike

5.3 查询点赞状态

• 接口: GET /api/v1/like/check

请求参数:

参数	类型	必填	说明
targetId	Long	是	目标ID
targetType	Integer	是	目标类型（1=文章，2=评论）

5.4 切换点赞状态

• 接口: POST /api/v1/like/toggle

---

6. 收藏管理接口

6.1 收藏文章

• 接口: POST /api/v1/collection/collect

请求参数:

字段	类型	必填	说明
articleId	Long	是	文章ID
folderId	Long	否	收藏夹ID

6.2 取消收藏文章

• 接口: DELETE /api/v1/collection/uncollect/{articleId}

6.3 查询收藏状态

• 接口: GET /api/v1/collection/check/{articleId}

6.4 创建收藏夹

• 接口: POST /api/v1/collection/folder/create

请求参数:

字段	类型	必填	说明
name	String	是	收藏夹名称
description	String	否	收藏夹描述

6.5 删除收藏夹

• 接口: DELETE /api/v1/collection/folder/delete/{folderId}

6.6 查询收藏夹列表

• 接口: GET /api/v1/collection/folder/list

6.7 分页查询收藏列表

• 接口: GET /api/v1/collection/list

请求参数:

参数	类型	必填	说明
current	Integer	是	页码
size	Integer	是	每页数量
folderId	Long	否	收藏夹ID

---

7. 关注管理接口

7.1 关注用户

• 接口: POST /api/v1/follow/follow

请求参数:

字段	类型	必填	说明
followingId	Long	是	被关注者ID

7.2 取消关注用户

• 接口: DELETE /api/v1/follow/unfollow/{followingId}

7.3 查询关注状态

• 接口: GET /api/v1/follow/check/{followingId}

7.4 查询关注列表

• 接口: GET /api/v1/follow/following/list

请求参数:

参数	类型	必填	说明
userId	Long	是	用户ID
current	Integer	是	页码
size	Integer	是	每页数量

7.5 查询粉丝列表

• 接口: GET /api/v1/follow/followers/list

7.6 查询关注数

• 接口: GET /api/v1/follow/following/count

7.7 查询粉丝数

• 接口: GET /api/v1/follow/followers/count

---

8. 通知管理接口

8.1 分页查询通知列表

• 接口: POST /api/v1/notification/list

8.2 标记通知为已读

• 接口: PUT /api/v1/notification/read/{notificationId}

8.3 批量标记通知为已读

• 接口: PUT /api/v1/notification/read/batch

请求参数:

字段	类型	必填	说明
-	List<Long>	是	通知ID列表

8.4 标记所有通知为已读

• 接口: PUT /api/v1/notification/read/all

8.5 清空所有通知

• 接口: DELETE /api/v1/notification/clear/all

8.6 查询未读通知数量

• 接口: GET /api/v1/notification/unread/count

---

9. 草稿箱管理接口

9.1 保存草稿

• 接口: POST /api/v1/draft/save

请求参数:

字段	类型	必填	说明
title	String	否	草稿标题
content	String	否	草稿内容
coverImage	String	否	封面图片
categoryId	Long	否	分类ID
tagIds	List<Long>	否	标签ID列表

9.2 删除草稿

• 接口: DELETE /api/v1/draft/delete/{draftId}

9.3 查询草稿详情

• 接口: GET /api/v1/draft/{draftId}

9.4 分页查询草稿列表

• 接口: GET /api/v1/draft/list

请求参数:

参数	类型	必填	说明
current	Integer	是	页码
size	Integer	是	每页数量

9.5 查询最新草稿

• 接口: GET /api/v1/draft/latest

---

附录：数据模型

ArticleResponseDTO（文章响应）

字段	类型	说明
id	Long	文章ID
title	String	文章标题
slug	String	文章别名
summary	String	文章摘要
content	String	文章内容（Markdown格式）
contentHtml	String	渲染后的HTML内容
coverImage	String	封面图片URL
authorId	Long	作者用户ID
authorName	String	作者用户名
categoryId	Long	分类ID
categoryName	String	分类名称
tags	List<TagResponseDTO>	标签列表
viewCount	Integer	浏览次数
likeCount	Integer	点赞数
commentCount	Integer	评论数
collectCount	Integer	收藏数
isTop	Integer	是否置顶
isEssence	Integer	是否精华
isPublished	Integer	是否发布
status	Integer	文章状态
publishTime	Date	发布时间
createTime	Date	创建时间
updateTime	Date	更新时间
isLiked	Boolean	当前用户是否点赞
isCollected	Boolean	当前用户是否收藏

ArticleListResponseDTO（文章列表响应）

字段	类型	说明
id	Long	文章ID
title	String	文章标题
slug	String	文章别名
summary	String	文章摘要
coverImage	String	封面图片URL
authorId	Long	作者用户ID
authorName	String	作者用户名
authorAvatar	String	作者头像
categoryId	Long	分类ID
categoryName	String	分类名称
tags	List<TagResponseDTO>	标签列表
viewCount	Integer	浏览次数
likeCount	Integer	点赞数
commentCount	Integer	评论数
collectCount	Integer	收藏数
isTop	Integer	是否置顶
isEssence	Integer	是否精华
publishTime	Date	发布时间
createTime	Date	创建时间
isLiked	Boolean	当前用户是否点赞
isCollected	Boolean	当前用户是否收藏

CommentResponseDTO（评论响应）

字段	类型	说明
id	Long	评论ID
articleId	Long	文章ID
userId	Long	评论用户ID
userName	String	评论用户名
userAvatar	String	评论用户头像
parentId	Long	父评论ID
replyToId	Long	回复的评论ID
replyToName	String	回复的用户名
content	String	评论内容
contentHtml	String	渲染后的HTML内容
likeCount	Integer	点赞数
replyCount	Integer	回复数
isAuthor	Integer	是否为作者评论
status	Integer	状态
createTime	Date	创建时间
updateTime	Date	更新时间
isLiked	Boolean	当前用户是否点赞
children	List<CommentResponseDTO>	子评论列表

CategoryResponseDTO（分类响应）

字段	类型	说明
id	Long	分类ID
name	String	分类名称
slug	String	分类别名
description	String	分类描述
icon	String	分类图标
sortOrder	Integer	排序序号
parentId	Long	父分类ID
articleCount	Integer	该分类下的文章数量
isEnabled	Integer	是否启用
createTime	Date	创建时间
updateTime	Date	更新时间

TagResponseDTO（标签响应）

字段	类型	说明
id	Long	标签ID
name	String	标签名称
slug	String	标签别名
description	String	标签描述
color	String	标签颜色
articleCount	Integer	使用该标签的文章数量
isEnabled	Integer	是否启用
createTime	Date	创建时间
updateTime	Date	更新时间