MonkeyBall2/PBlog
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
PBlog/API_DOCUMENTATION.md

18 KiB
Raw Permalink Blame History

灵猴社博客系统 API 接口文档

📋 基本信息

  • 服务器地址: http://localhost:8089
  • API版本: v1.0
  • 文档版本: v1.0
  • 最后更新: 2025-01-16

📊 状态码说明

状态码 说明
200 请求成功
201 创建成功
400 请求参数错误
401 未授权/Token无效
403 权限不足
404 资源不存在
500 服务器内部错误

🔗 API接口列表

1. 认证相关接口

1.1 用户注册

  • 接口: POST /api/auth/register
  • 描述: 用户注册新账户
  • 需要认证: ❌

请求参数:

{
  "username": "string",     // 用户名 (3-50字符)
  "email": "string",        // 邮箱地址
  "password": "string"      // 密码 (最少6位)
}

响应示例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "role": "user",
    "created_at": "2025-01-16T10:30:00Z",
    "updated_at": "2025-01-16T10:30:00Z"
  }
}

1.2 用户登录

  • 接口: POST /api/auth/login
  • 描述: 用户登录获取Token
  • 需要认证: ❌

请求参数:

{
  "email": "string",        // 邮箱地址
  "password": "string"      // 密码
}

响应示例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "role": "user",
    "created_at": "2025-01-16T10:30:00Z",
    "updated_at": "2025-01-16T10:30:00Z"
  }
}

1.3 刷新Token

  • 接口: POST /api/auth/refresh
  • 描述: 刷新JWT Token
  • 需要认证: ❌

请求参数:

{
  "token": "string"         // 当前的JWT Token
}

响应示例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

1.4 获取用户资料

  • 接口: GET /api/profile
  • 描述: 获取当前用户的个人资料
  • 需要认证: ✅

响应示例:

{
  "id": 1,
  "username": "testuser",
  "email": "test@example.com",
  "role": "user",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}

2. 文章管理接口

2.1 获取文章列表

  • 接口: GET /api/articles
  • 描述: 获取文章列表（支持分页和筛选）
  • 需要认证: ❌

查询参数:

参数 类型 必需 描述
page int ❌ 页码，默认1
page_size int ❌ 每页数量，默认10，最大100
status string ❌ 文章状态：published/draft/private
tag string ❌ 标签名称
user_id int ❌ 作者ID

响应示例:

{
  "articles": [
    {
      "id": 1,
      "title": "我的第一篇文章",
      "slug": "my-first-article",
      "markdown_content": "# 标题\n\n内容...",
      "html_content": "<h1>标题</h1><p>内容...</p>",
      "status": "published",
      "published_at": "2025-01-16T10:30:00Z",
      "created_at": "2025-01-16T10:30:00Z",
      "updated_at": "2025-01-16T10:30:00Z",
      "tags": [
        {
          "id": 1,
          "name": "技术",
          "created_at": "2025-01-16T10:30:00Z"
        }
      ],
      "user": {
        "id": 1,
        "username": "testuser",
        "email": "test@example.com",
        "role": "user"
      },
      "excerpt": "这是文章摘要..."
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 10
}

2.2 获取单篇文章

  • 接口: GET /api/articles/{slug}
  • 描述: 通过slug获取单篇文章详情
  • 需要认证: ❌（公开文章）

路径参数:

  • slug: 文章的URL友好标识

响应示例:

{
  "id": 1,
  "title": "我的第一篇文章",
  "slug": "my-first-article",
  "markdown_content": "# 标题\n\n内容...",
  "html_content": "<h1>标题</h1><p>内容...</p>",
  "status": "published",
  "published_at": "2025-01-16T10:30:00Z",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z",
  "tags": [
    {
      "id": 1,
      "name": "技术",
      "created_at": "2025-01-16T10:30:00Z"
    }
  ],
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "role": "user"
  }
}

2.3 创建文章

  • 接口: POST /api/articles
  • 描述: 创建新文章
  • 需要认证: ✅

请求参数:

{
  "title": "string",           // 文章标题 (1-200字符)
  "markdown_content": "string", // Markdown内容
  "status": "string",          // 状态: draft/published/private
  "tags": ["string"],          // 标签数组
  "slug": "string",            // 可选，自定义slug
  "published_at": "2025-01-16T10:30:00Z"  // 可选，定时发布时间
}

响应示例:

{
  "id": 1,
  "title": "我的第一篇文章",
  "slug": "my-first-article",
  "markdown_content": "# 标题\n\n内容...",
  "html_content": "<h1>标题</h1><p>内容...</p>",
  "status": "published",
  "published_at": "2025-01-16T10:30:00Z",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z",
  "tags": [
    {
      "id": 1,
      "name": "技术",
      "created_at": "2025-01-16T10:30:00Z"
    }
  ],
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "role": "user"
  }
}

2.4 更新文章

  • 接口: PUT /api/articles/{id}
  • 描述: 更新指定文章
  • 需要认证: ✅
  • 权限: 作者或管理员

路径参数:

  • id: 文章ID

请求参数:

{
  "title": "string",           // 可选，文章标题
  "markdown_content": "string", // 可选，Markdown内容
  "status": "string",          // 可选，状态
  "tags": ["string"],          // 可选，标签数组
  "slug": "string",            // 可选，自定义slug
  "published_at": "2025-01-16T10:30:00Z"  // 可选，发布时间
}

响应示例: 同创建文章

2.5 删除文章

  • 接口: DELETE /api/articles/{id}
  • 描述: 删除指定文章
  • 需要认证: ✅
  • 权限: 作者或管理员

路径参数:

  • id: 文章ID

响应示例:

{
  "message": "Article deleted successfully"
}

2.6 获取文章版本历史

  • 接口: GET /api/articles/{id}/versions
  • 描述: 获取文章的版本历史
  • 需要认证: ✅
  • 权限: 作者或管理员

路径参数:

  • id: 文章ID

响应示例:

{
  "versions": [
    {
      "id": 1,
      "article_id": 1,
      "markdown_content": "# 旧版本内容\n\n...",
      "created_at": "2025-01-16T10:30:00Z"
    }
  ]
}

3. 评论管理接口

3.1 获取文章评论

  • 接口: GET /api/comments/article/{article_id}
  • 描述: 获取指定文章的评论列表
  • 需要认证: ❌

路径参数:

  • article_id: 文章ID

查询参数:

参数 类型 必需 描述
page int ❌ 页码，默认1
page_size int ❌ 每页数量，默认20，最大100

响应示例:

{
  "comments": [
    {
      "id": 1,
      "article_id": 1,
      "user_id": 2,
      "markdown_content": "很好的文章！",
      "html_content": "<p>很好的文章！</p>",
      "created_at": "2025-01-16T10:30:00Z",
      "updated_at": "2025-01-16T10:30:00Z",
      "user": {
        "id": 2,
        "username": "commenter",
        "email": "commenter@example.com",
        "role": "user"
      }
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 20
}

3.2 获取单条评论

  • 接口: GET /api/comments/{id}
  • 描述: 获取指定评论详情
  • 需要认证: ❌

路径参数:

  • id: 评论ID

响应示例:

{
  "id": 1,
  "article_id": 1,
  "user_id": 2,
  "markdown_content": "很好的文章！",
  "html_content": "<p>很好的文章！</p>",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z",
  "user": {
    "id": 2,
    "username": "commenter",
    "email": "commenter@example.com",
    "role": "user"
  }
}

3.3 添加评论

  • 接口: POST /api/comments/article/{article_id}
  • 描述: 为指定文章添加评论
  • 需要认证: ✅

路径参数:

  • article_id: 文章ID

请求参数:

{
  "markdown_content": "string"  // 评论内容 (1-1000字符)
}

响应示例:

{
  "id": 1,
  "article_id": 1,
  "user_id": 2,
  "markdown_content": "很好的文章！",
  "html_content": "<p>很好的文章！</p>",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z",
  "user": {
    "id": 2,
    "username": "commenter",
    "email": "commenter@example.com",
    "role": "user"
  }
}

3.4 更新评论

  • 接口: PUT /api/comments/{id}
  • 描述: 更新指定评论
  • 需要认证: ✅
  • 权限: 评论作者或管理员

路径参数:

  • id: 评论ID

请求参数:

{
  "markdown_content": "string"  // 更新后的评论内容
}

响应示例: 同添加评论

3.5 删除评论

  • 接口: DELETE /api/comments/{id}
  • 描述: 删除指定评论
  • 需要认证: ✅
  • 权限: 评论作者或管理员

路径参数:

  • id: 评论ID

响应示例:

{
  "message": "Comment deleted successfully"
}

4. 媒体管理接口

4.1 上传媒体文件

  • 接口: POST /api/media/upload
  • 描述: 上传媒体文件（图片、视频等）
  • 需要认证: ✅
  • Content-Type: multipart/form-data

请求参数:

  • file: 文件对象（最大10MB）

支持的文件类型:

  • 图片: image/jpeg, image/png, image/gif, image/webp
  • 视频: video/mp4, video/webm, video/ogg

响应示例:

{
  "id": 1,
  "filename": "uuid_timestamp.jpg",
  "url": "/uploads/uuid_timestamp.jpg",
  "mime_type": "image/jpeg",
  "size": 1048576
}

4.2 获取媒体文件列表

  • 接口: GET /api/media
  • 描述: 获取媒体文件列表
  • 需要认证: ✅

查询参数:

参数 类型 必需 描述
page int ❌ 页码，默认1
page_size int ❌ 每页数量，默认20，最大100

响应示例:

{
  "media": [
    {
      "id": 1,
      "user_id": 1,
      "filename": "uuid_timestamp.jpg",
      "url": "/uploads/uuid_timestamp.jpg",
      "mime_type": "image/jpeg",
      "size": 1048576,
      "created_at": "2025-01-16T10:30:00Z",
      "updated_at": "2025-01-16T10:30:00Z",
      "user": {
        "id": 1,
        "username": "testuser",
        "email": "test@example.com",
        "role": "user"
      }
    }
  ],
  "total": 10,
  "page": 1,
  "page_size": 20
}

4.3 获取媒体文件信息

  • 接口: GET /api/media/{id}
  • 描述: 获取指定媒体文件信息
  • 需要认证: ✅
  • 权限: 文件上传者或管理员

路径参数:

  • id: 媒体文件ID

响应示例:

{
  "id": 1,
  "user_id": 1,
  "filename": "uuid_timestamp.jpg",
  "url": "/uploads/uuid_timestamp.jpg",
  "mime_type": "image/jpeg",
  "size": 1048576,
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z",
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "role": "user"
  }
}

4.4 删除媒体文件

  • 接口: DELETE /api/media/{id}
  • 描述: 删除指定媒体文件
  • 需要认证: ✅
  • 权限: 文件上传者或管理员

路径参数:

  • id: 媒体文件ID

响应示例:

{
  "message": "Media deleted successfully"
}

5. 管理员接口

5.1 获取用户列表

  • 接口: GET /api/admin/users
  • 描述: 获取系统用户列表
  • 需要认证: ✅
  • 权限: 管理员

查询参数:

参数 类型 必需 描述
page int ❌ 页码，默认1
page_size int ❌ 每页数量，默认20，最大100
search string ❌ 搜索关键词（用户名或邮箱）
role string ❌ 角色过滤：user/admin

响应示例:

{
  "users": [
    {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "role": "user",
      "created_at": "2025-01-16T10:30:00Z",
      "updated_at": "2025-01-16T10:30:00Z",
      "article_count": 5,
      "comment_count": 10
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20
}

5.2 更新用户角色

  • 接口: PUT /api/admin/users/{id}/role
  • 描述: 更新用户角色
  • 需要认证: ✅
  • 权限: 管理员

路径参数:

  • id: 用户ID

请求参数:

{
  "role": "string"  // 角色: user/admin
}

响应示例:

{
  "id": 1,
  "username": "testuser",
  "email": "test@example.com",
  "role": "admin",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}

5.3 删除用户

  • 接口: DELETE /api/admin/users/{id}
  • 描述: 删除指定用户
  • 需要认证: ✅
  • 权限: 管理员

路径参数:

  • id: 用户ID

响应示例:

{
  "message": "User deleted successfully"
}

5.4 批量删除文章

  • 接口: DELETE /api/admin/articles
  • 描述: 批量删除文章
  • 需要认证: ✅
  • 权限: 管理员

请求参数:

{
  "article_ids": [1, 2, 3]  // 要删除的文章ID数组
}

响应示例:

{
  "message": "Articles deleted successfully",
  "deleted_count": 3
}

5.5 管理评论

  • 接口: POST /api/admin/comments/manage
  • 描述: 批量管理评论
  • 需要认证: ✅
  • 权限: 管理员

请求参数:

{
  "comment_ids": [1, 2, 3],  // 评论ID数组
  "action": "string"         // 操作类型: delete/approve
}

响应示例:

{
  "message": "Comments managed successfully",
  "affected_count": 3
}

5.6 获取标签列表

  • 接口: GET /api/admin/tags
  • 描述: 获取系统标签列表
  • 需要认证: ✅
  • 权限: 管理员

查询参数:

参数 类型 必需 描述
page int ❌ 页码，默认1
page_size int ❌ 每页数量，默认20，最大100
search string ❌ 搜索关键词

响应示例:

{
  "tags": [
    {
      "id": 1,
      "name": "技术",
      "created_at": "2025-01-16T10:30:00Z",
      "updated_at": "2025-01-16T10:30:00Z",
      "article_count": 10
    }
  ],
  "total": 20,
  "page": 1,
  "page_size": 20
}

5.7 删除标签

  • 接口: DELETE /api/admin/tags/{id}
  • 描述: 删除指定标签
  • 需要认证: ✅
  • 权限: 管理员

路径参数:

  • id: 标签ID

响应示例:

{
  "message": "Tag deleted successfully"
}

5.8 获取系统统计

  • 接口: GET /api/admin/stats
  • 描述: 获取系统统计信息
  • 需要认证: ✅
  • 权限: 管理员

响应示例:

{
  "total_users": 100,
  "total_articles": 500,
  "total_comments": 1000,
  "total_media": 200,
  "published_articles": 450,
  "draft_articles": 50
}

5.9 获取最近活动

  • 接口: GET /api/admin/activities
  • 描述: 获取系统最近活动
  • 需要认证: ✅
  • 权限: 管理员

查询参数:

参数 类型 必需 描述
limit int ❌ 数量限制，默认10，最大50

响应示例:

{
  "activities": [
    {
      "type": "article",
      "data": {
        "id": 1,
        "title": "新文章",
        "user": {
          "id": 1,
          "username": "testuser"
        }
      },
      "created_at": "2025-01-16T10:30:00Z"
    }
  ]
}

6. 系统接口

6.1 健康检查

  • 接口: GET /health
  • 描述: 系统健康状态检查
  • 需要认证: ❌

响应示例:

{
  "status": "ok",
  "message": "PBlog API is running"
}

🔧 错误处理

所有接口在发生错误时，都会返回统一的错误格式：

{
  "error": "错误描述信息"
}

常见错误

400 Bad Request

{
  "error": "Invalid request parameters"
}

401 Unauthorized

{
  "error": "Authorization header is required"
}

403 Forbidden

{
  "error": "Permission denied"
}

404 Not Found

{
  "error": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

📝 使用示例

完整的用户注册到发布文章流程

1. 用户注册

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "newuser@example.com",
    "password": "password123"
  }'

2. 用户登录

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "password123"
  }'

3. 创建文章

curl -X POST http://localhost:8080/api/articles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "我的第一篇技术文章",
    "markdown_content": "# 标题\n\n这是我的第一篇文章内容...",
    "status": "published",
    "tags": ["技术", "编程", "Go"]
  }'

4. 获取文章列表

curl -X GET "http://localhost:8080/api/articles?page=1&page_size=10&status=published"

5. 添加评论

curl -X POST http://localhost:8080/api/comments/article/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "markdown_content": "很好的文章，感谢分享！"
  }'

🔍 调试建议

1. 使用健康检查验证服务状态

curl http://localhost:8080/health

2. 检查Token有效性

curl -X GET http://localhost:8080/api/profile \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

3. 查看详细错误信息

在开发环境中，可以通过查看服务器日志获取详细的错误信息。

📚 更多资源

注意: 本文档基于开发环境编写，生产环境使用时请注意：

  1. 修改默认的JWT密钥
  2. 使用HTTPS协议
  3. 配置适当的CORS策略
  4. 设置合理的请求频率限制

如有疑问或建议，请联系技术支持团队。