177 lines
4.2 KiB
Markdown
177 lines
4.2 KiB
Markdown
# 微博客 RESTful API 文档
|
||
|
||
## 简介
|
||
|
||
本 API 提供了一个用于管理博客文章的接口，支持使用 Markdown 格式存储内容，并且支持分页查询。后端基于 Go 语言开发，支持 MySQL
|
||
和 PostgreSQL 数据库。
|
||
|
||
## 基本信息
|
||
|
||
- **Base URL**: `https://wqyblog-cn-api-eqvsnqpylk.cn-shanghai.fcapp.run/api`
|
||
- **Content-Type**: `application/json`
|
||
- **Authorization**: 使用 JWT
|
||
进行身份验证。在所有需要身份验证的请求中，必须在请求头中包含 `Authorization: Bearer {token}`。
|
||
|
||
## 提示
|
||
|
||
- 在使用此 API 时，请确保使用 HTTPS 来保护数据传输的安全性。
|
||
|
||
- 案例网站：https://wqyblog.cn/
|
||
|
||
## 测试认证密码
|
||
|
||
- **用户名**: `admin`
|
||
- **密码**: `123456@321`
|
||
|
||
## 认证
|
||
|
||
### 1. 用户登录
|
||
|
||
**描述**: 生成一个 JWT，用于后续的 API 调用。
|
||
|
||
- **URL**: `/auth/login`
|
||
- **方法**: `POST`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "your_secure_password"
|
||
}
|
||
```
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"token": "jwt_token"
|
||
}
|
||
```
|
||
- **说明**: 成功登录后，返回 JWT 令牌，用于后续请求的身份认证。
|
||
|
||
## 博文管理
|
||
|
||
### 2. 获取博文列表
|
||
|
||
**描述**: 获取博客文章列表，支持分页。
|
||
|
||
- **URL**: `/posts`
|
||
- **方法**: `GET`
|
||
- **请求参数**:
|
||
- `page` (可选): 页码，默认值为 `1`。
|
||
- `limit` (可选): 每页显示的记录数量，默认值为 `10`。
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"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`
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"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`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"title": "New Post Title",
|
||
"content": "Markdown content here..."
|
||
}
|
||
```
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"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`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"title": "Updated Post Title",
|
||
"content": "Updated markdown content..."
|
||
}
|
||
```
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"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`
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"message": "Post deleted successfully"
|
||
}
|
||
```
|
||
- **说明**: 删除指定 `id` 的博文。如果该 `id` 对应的博文不存在，返回 `404` 错误。
|
||
|
||
## 错误处理
|
||
|
||
API 在发生错误时会返回以下格式的错误响应：
|
||
|
||
```json
|
||
{
|
||
"error": "Error description"
|
||
}
|
||
```
|
||
|
||
- **401 Unauthorized**: 需要有效的 JWT 令牌，但令牌未提供或无效。
|
||
- **404 Not Found**: 请求的资源不存在（如博文不存在）。
|
||
- **400 Bad Request**: 请求参数无效或缺失。
|