博客 RESTful API 文档

简介

本 API 提供了一个用于管理博客文章的接口，支持使用 Markdown 格式存储内容，并且支持分页查询。后端基于 Go 语言开发，支持 MySQL 和 PostgreSQL 数据库。

基本信息

• Base URL: https://func-e-wiwafluoqc.cn-shanghai.fcapp.run/api
• Content-Type: application/json
• Authorization: 使用 JWT 进行身份验证。在所有需要身份验证的请求中，必须在请求头中包含 Authorization: Bearer {token}。

测试认证密码

• 用户名: admin
• 密码: 123456@321

认证

1. 用户登录

描述: 生成一个 JWT，用于后续的 API 调用。

• URL: /auth/login
• 方法: POST
• 请求体:

  {
      "username": "admin",
      "password": "your_secure_password"
  }
  

• 响应:

  {
      "token": "jwt_token"
  }
  

• 说明: 成功登录后，返回 JWT 令牌，用于后续请求的身份认证。

博文管理

2. 获取博文列表

描述: 获取博客文章列表，支持分页。

• URL: /posts
• 方法: GET
• 请求参数:
  • page (可选): 页码，默认值为 1。
  • limit (可选): 每页显示的记录数量，默认值为 10。
• 响应:

  {
      "page": 1,
      "limit": 10,
      "data": [
          {
              "ID": 1,
              "CreatedAt": "2024-08-20T12:00:00Z",
              "UpdatedAt": "2024-08-20T12:00:00Z",
              "DeletedAt": null,
              "Title": "First Post",
              "Content": "Markdown content here..."
          }
      ]
  }
  

• 说明: 返回分页后的博文列表。

3. 获取单个博文

描述: 根据 id 获取指定的博客文章。

• URL: /posts/:id
• 方法: GET
• 响应:

  {
      "ID": 1,
      "CreatedAt": "2024-08-20T12:00:00Z",
      "UpdatedAt": "2024-08-20T12:00:00Z",
      "DeletedAt": null,
      "Title": "First Post",
      "Content": "Markdown content here..."
  }
  

• 说明: 返回指定 id 的博文详情。如果该 id 对应的博文不存在，返回 404 错误。

4. 创建博文

描述: 创建一篇新的博客文章。

• URL: /posts
• 方法: POST
• 请求体:

  {
      "title": "New Post Title",
      "content": "Markdown content here..."
  }
  

• 响应:

  {
      "ID": 3,
      "CreatedAt": "2024-08-22T12:00:00Z",
      "UpdatedAt": "2024-08-22T12:00:00Z",
      "DeletedAt": null,
      "Title": "New Post Title",
      "Content": "Markdown content here..."
  }
  

• 说明: 创建一篇新的博文，并返回创建的博文信息。

5. 更新博文

描述: 更新指定 id 的博客文章。

• URL: /posts/:id
• 方法: PUT
• 请求体:

  {
      "title": "Updated Post Title",
      "content": "Updated markdown content..."
  }
  

• 响应:

  {
      "ID": 1,
      "CreatedAt": "2024-08-20T12:00:00Z",
      "UpdatedAt": "2024-08-22T13:00:00Z",
      "DeletedAt": null,
      "Title": "Updated Post Title",
      "Content": "Updated markdown content..."
  }
  

• 说明: 更新指定 id 的博文。如果该 id 对应的博文不存在，返回 404 错误。

6. 删除博文

描述: 删除指定 id 的博客文章。

• URL: /posts/:id
• 方法: DELETE
• 响应:

  {
      "message": "Post deleted successfully"
  }
  

• 说明: 删除指定 id 的博文。如果该 id 对应的博文不存在，返回 404 错误。

错误处理

API 在发生错误时会返回以下格式的错误响应：

{
    "error": "Error description"
}

• 401 Unauthorized: 需要有效的 JWT 令牌，但令牌未提供或无效。
• 404 Not Found: 请求的资源不存在（如博文不存在）。
• 400 Bad Request: 请求参数无效或缺失。

例外情况

在使用此 API 时，请确保使用 HTTPS 来保护数据传输的安全性。