18 KiB

Raw Permalink Blame History

新闻分类器后端 API 文档

基础信息

Base URL: http://localhost:8080
API 版本: v1
响应格式: JSON
字符编码: UTF-8

统一响应格式

所有接口返回统一的 RestBean 格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

状态码说明

状态码	说明
200	操作成功
400	请求参数错误
401	未认证（需要登录）
403	无权限访问
404	资源不存在
500	服务器内部错误

预定义状态码（RestCode）

code	message	说明
200	操作成功	SUCCESS
400	请求参数错误	FAILURE
401	请先登录	-
403	无权限访问	-
404	数据不存在	DATA_NOT_FOUND
500	服务端错误	SYSTEM_ERROR
10001	用户名或密码错误	USERNAME_OR_PASSWORD_ERROR
10002	Token已过期	TOKEN_EXPIRE

认证说明

Token 认证

需要认证的接口需要在请求头中携带 Token：

Authorization: Bearer {token}

Token 获取

通过登录接口获取，参见用户登录

一、用户接口

Base Path: `/api/v1/user`

3.1 用户注册

接口地址: POST /api/v1/user/register

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
username	String	是	用户名（唯一，50字符以内）
password	String	是	密码
email	String	是	邮箱（唯一）

请求示例:

{
  "username": "testuser",
  "password": "123456",
  "email": "test@example.com"
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

错误响应:

{
  "code": 400,
  "message": "用户名已被使用",
  "data": null
}

3.2 用户登录

接口地址: POST /api/v1/user/login

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
username	String	是	用户名
password	String	是	密码

请求示例:

{
  "username": "testuser",
  "password": "123456"
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

错误响应:

{
  "code": 404,
  "message": "用户不存在",
  "data": null
}

{
  "code": 10001,
  "message": "用户名或密码错误",
  "data": null
}

{
  "code": 403,
  "message": "用户已被禁用",
  "data": null
}

3.3 获取用户信息

接口地址: GET /api/v1/user/info

是否需要认证: 是

请求头:

Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "status": 1,
    "createdAt": "2024-01-01T10:00:00",
    "updatedAt": "2024-01-01T10:00:00"
  }
}

二、分类管理接口

Base Path: `/api/v1/categories`

说明: 所有分类接口均无需认证，公开访问

2.1 获取所有分类

接口地址: GET /api/v1/categories

是否需要认证: 否

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "娱乐",
      "newsCount": null
    },
    {
      "id": 2,
      "name": "体育",
      "newsCount": null
    },
    {
      "id": 3,
      "name": "财经",
      "newsCount": null
    },
    {
      "id": 4,
      "name": "科技",
      "newsCount": null
    },
    {
      "id": 5,
      "name": "军事",
      "newsCount": null
    },
    {
      "id": 6,
      "name": "汽车",
      "newsCount": null
    },
    {
      "id": 7,
      "name": "政务",
      "newsCount": null
    },
    {
      "id": 8,
      "name": "健康",
      "newsCount": null
    },
    {
      "id": 9,
      "name": "AI",
      "newsCount": null
    }
  ]
}

2.2 获取分类及新闻数量

接口地址: GET /api/v1/categories/with-count

是否需要认证: 否

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "娱乐",
      "newsCount": 152
    },
    {
      "id": 2,
      "name": "体育",
      "newsCount": 89
    },
    {
      "id": 4,
      "name": "科技",
      "newsCount": 234
    }
  ]
}

2.3 获取分类详情

接口地址: GET /api/v1/categories/{id}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
id	Integer	是	分类ID

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 4,
    "name": "科技",
    "newsCount": null
  }
}

错误响应:

{
  "code": 404,
  "message": "数据不存在",
  "data": null
}

2.4 创建分类

接口地址: POST /api/v1/categories

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
name	String	是	分类名称（唯一，50字符以内）

请求示例:

{
  "name": "游戏"
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 10,
    "name": "游戏",
    "newsCount": null
  }
}

错误响应:

{
  "code": 400,
  "message": "分类名称已存在",
  "data": null
}

2.5 更新分类

接口地址: PUT /api/v1/categories/{id}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
id	Integer	是	分类ID

请求参数:

参数名	类型	必填	说明
name	String	是	分类名称

请求示例:

{
  "name": "电竞游戏"
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 10,
    "name": "电竞游戏",
    "newsCount": null
  }
}

2.6 删除分类

接口地址: DELETE /api/v1/categories/{id}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
id	Integer	是	分类ID

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

三、新闻管理接口

Base Path: `/api/v1/news`

说明: 所有新闻接口均无需认证，公开访问

3.1 获取新闻列表

接口地址: GET /api/v1/news/list

是否需要认证: 否

查询参数:

参数名	类型	必填	默认值	说明
page	Integer	否	1	页码
size	Integer	否	20	每页大小
categoryId	Integer	否	-	分类ID筛选
source	String	否	-	来源筛选（如：网易、36kr）
keyword	String	否	-	搜索关键词（标题或内容）
sortBy	String	否	createdAt	排序字段
sortOrder	String	否	DESC	排序方向（ASC/DESC）

请求示例:

GET /api/v1/news/list?page=1&size=10&categoryId=4&source=网易

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "url": "https://news.example.com/tech/001",
        "title": "AI技术突破：新一代大语言模型发布",
        "categoryId": 9,
        "categoryName": "AI",
        "publishTime": "2024-01-15 10:30:00",
        "author": "张三",
        "source": "网易",
        "content": "正文内容...",
        "createdAt": "2024-01-15 11:00:00"
      },
      {
        "id": 2,
        "url": "https://news.example.com/tech/002",
        "title": "量子计算取得重大进展",
        "categoryId": 4,
        "categoryName": "科技",
        "publishTime": "2024-01-15 09:00:00",
        "author": "李四",
        "source": "36kr",
        "content": "正文内容...",
        "createdAt": "2024-01-15 10:00:00"
      }
    ],
    "total": 156,
    "page": 1,
    "size": 10,
    "pages": 16
  }
}

3.2 获取新闻详情

接口地址: GET /api/v1/news/{id}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
id	Long	是	新闻ID

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "url": "https://news.example.com/tech/001",
    "title": "AI技术突破：新一代大语言模型发布",
    "categoryId": 9,
    "categoryName": "AI",
    "publishTime": "2024-01-15 10:30:00",
    "author": "张三",
    "source": "网易",
    "content": "完整的正文内容...",
    "createdAt": "2024-01-15 11:00:00"
  }
}

3.3 创建新闻

接口地址: POST /api/v1/news

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
url	String	是	新闻URL（唯一，500字符以内）
title	String	是	标题（255字符以内）
categoryId	Integer	否	分类ID
publishTime	LocalDateTime	否	发布时间
author	String	否	作者
source	String	否	来源（如：网易、36kr）
content	String	是	正文内容

请求示例:

{
  "url": "https://news.example.com/tech/003",
  "title": "5G网络建设加速推进",
  "categoryId": 4,
  "publishTime": "2024-01-16T08:00:00",
  "author": "王五",
  "source": "36kr",
  "content": "完整的新闻正文内容..."
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 3,
    "url": "https://news.example.com/tech/003",
    "title": "5G网络建设加速推进",
    "categoryId": 4,
    "categoryName": "科技",
    "publishTime": "2024-01-16 08:00:00",
    "author": "王五",
    "source": "36kr",
    "content": "完整的新闻正文内容...",
    "createdAt": "2024-01-16 09:00:00"
  }
}

错误响应:

{
  "code": 400,
  "message": "该URL的新闻已存在",
  "data": null
}

{
  "code": 400,
  "message": "指定的分类不存在",
  "data": null
}

3.4 更新新闻

接口地址: PUT /api/v1/news

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
id	Long	是	新闻ID
title	String	否	标题
categoryId	Integer	否	分类ID
publishTime	LocalDateTime	否	发布时间
author	String	否	作者
source	String	否	来源
content	String	否	正文内容

请求示例:

{
  "id": 3,
  "title": "5G网络建设加速推进（更新）",
  "categoryId": 9
}

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 3,
    "url": "https://news.example.com/tech/003",
    "title": "5G网络建设加速推进（更新）",
    "categoryId": 9,
    "categoryName": "AI",
    "publishTime": "2024-01-16 08:00:00",
    "author": "王五",
    "source": "36kr",
    "content": "完整的新闻正文内容...",
    "createdAt": "2024-01-16 09:00:00"
  }
}

3.5 删除新闻

接口地址: DELETE /api/v1/news/{id}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
id	Long	是	新闻ID

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.6 批量删除新闻

接口地址: DELETE /api/v1/news/batch

是否需要认证: 否

请求参数:

参数名	类型	必填	说明
-	Array[Long]	是	新闻ID列表

请求示例:

[1, 2, 3, 4, 5]

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.7 搜索新闻

接口地址: GET /api/v1/news/search

是否需要认证: 否

查询参数:

参数名	类型	必填	默认值	说明
keyword	String	是	-	搜索关键词
page	Integer	否	1	页码
size	Integer	否	20	每页大小

请求示例:

GET /api/v1/news/search?keyword=AI&page=1&size=10

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "url": "https://news.example.com/tech/001",
        "title": "AI技术突破：新一代大语言模型发布",
        "categoryId": 9,
        "categoryName": "AI",
        "publishTime": "2024-01-15 10:30:00",
        "author": "张三",
        "source": "网易",
        "content": "正文内容...",
        "createdAt": "2024-01-15 11:00:00"
      }
    ],
    "total": 23,
    "page": 1,
    "size": 10,
    "pages": 3
  }
}

3.8 按分类获取新闻

接口地址: GET /api/v1/news/category/{categoryId}

是否需要认证: 否

路径参数:

参数名	类型	必填	说明
categoryId	Integer	是	分类ID

查询参数:

参数名	类型	必填	默认值	说明
page	Integer	否	1	页码
size	Integer	否	20	每页大小

请求示例:

GET /api/v1/news/category/4?page=1&size=10

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 2,
        "url": "https://news.example.com/tech/002",
        "title": "量子计算取得重大进展",
        "categoryId": 4,
        "categoryName": "科技",
        "publishTime": "2024-01-15 09:00:00",
        "author": "李四",
        "source": "36kr",
        "content": "正文内容...",
        "createdAt": "2024-01-15 10:00:00"
      }
    ],
    "total": 89,
    "page": 1,
    "size": 10,
    "pages": 9
  }
}

3.9 获取最新新闻

接口地址: GET /api/v1/news/latest

是否需要认证: 否

查询参数:

参数名	类型	必填	默认值	说明
page	Integer	否	1	页码
size	Integer	否	20	每页大小

请求示例:

GET /api/v1/news/latest?page=1&size=10

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 10,
        "url": "https://news.example.com/latest/001",
        "title": "今日要闻汇总",
        "categoryId": null,
        "categoryName": null,
        "publishTime": "2024-01-16 12:00:00",
        "author": "编辑",
        "source": "网易",
        "content": "正文内容...",
        "createdAt": "2024-01-16 12:30:00"
      }
    ],
    "total": 1234,
    "page": 1,
    "size": 10,
    "pages": 124
  }
}

3.10 获取新闻统计数据

接口地址: GET /api/v1/news/statistics

是否需要认证: 否

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "totalNews": 5678,
    "categoryStats": {
      "娱乐": 1234,
      "体育": 890,
      "财经": 756,
      "科技": 1523,
      "军事": 456,
      "汽车": 234,
      "政务": 123,
      "健康": 345,
      "AI": 117
    },
    "sourceStats": {
      "网易": 3456,
      "36kr": 2222
    }
  }
}

四、数据模型

4.1 RestBean

通用响应封装类。

{
  code: number,       // 状态码
  message: string,    // 提示消息
  data: T            // 返回数据
}

4.2 PageResult

分页结果封装类。

{
  records: T[],       // 数据列表
  total: number,      // 总记录数
  page: number,       // 当前页
  size: number,       // 每页大小
  pages: number       // 总页数
}

4.3 UserDto

用户数据传输对象。

{
  id?: number,              // 用户ID
  username: string,         // 用户名
  email: string,            // 邮箱
  password?: string,        // 密码（注册/登录时需要）
  status?: number,          // 状态（1=正常 0=禁用）
  createdAt?: string,       // 创建时间
  updatedAt?: string        // 更新时间
}

4.4 CategoryDto

分类数据传输对象。

{
  id: number,               // 分类ID
  name: string,             // 分类名称
  newsCount?: number        // 该分类下的新闻数量
}

4.5 NewsDto

新闻数据传输对象。

{
  id: number,               // 新闻ID
  url: string,              // 新闻URL
  title: string,            // 标题
  categoryId: number,       // 分类ID
  categoryName: string,     // 分类名称
  publishTime: string,      // 发布时间
  author: string,           // 作者
  source: string,           // 来源（网易/36kr）
  content: string,          // 正文内容
  createdAt: string         // 入库时间
}

五、常见错误

5.1 参数校验错误

{
  "code": 400,
  "message": "分类名称不能为空",
  "data": null
}

5.2 资源不存在

{
  "code": 404,
  "message": "数据不存在",
  "data": null
}

5.3 服务器错误

{
  "code": 500,
  "message": "服务端错误",
  "data": null
}

六、接口调试

6.1 Swagger UI

启动项目后访问：http://localhost:8080/swagger-ui.html

在 Swagger UI 中可以直接测试所有接口。

6.2 cURL 示例

用户注册

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

用户登录

curl -X POST http://localhost:8080/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"123456"}'

获取新闻列表

curl -X GET "http://localhost:8080/api/v1/news/list?page=1&size=10"

创建新闻

curl -X POST http://localhost:8080/api/v1/news \
  -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/news/001",
    "title":"测试新闻",
    "categoryId":4,
    "content":"这是新闻正文内容"
  }'

附录

初始分类数据

ID	名称
1	娱乐
2	体育
3	财经
4	科技
5	军事
6	汽车
7	政务
8	健康
9	AI

版本历史

版本	日期	说明
v1.0	2024-01-16	初始版本

18 KiB Raw Permalink Blame History Unescape Escape

新闻分类器后端 API 文档

基础信息

统一响应格式

状态码说明

预定义状态码（RestCode）

认证说明

Token 认证

Token 获取

一、用户接口

Base Path: /api/v1/user

3.1 用户注册

3.2 用户登录

3.3 获取用户信息

二、分类管理接口

Base Path: /api/v1/categories

2.1 获取所有分类

2.2 获取分类及新闻数量

2.3 获取分类详情

2.4 创建分类

2.5 更新分类

2.6 删除分类

三、新闻管理接口

Base Path: /api/v1/news

3.1 获取新闻列表

3.2 获取新闻详情

3.3 创建新闻

3.4 更新新闻

3.5 删除新闻

3.6 批量删除新闻

3.7 搜索新闻

3.8 按分类获取新闻

3.9 获取最新新闻

3.10 获取新闻统计数据

四、数据模型

4.1 RestBean

4.2 PageResult

4.3 UserDto

4.4 CategoryDto

4.5 NewsDto

五、常见错误

5.1 参数校验错误

5.2 资源不存在

5.3 服务器错误

六、接口调试

6.1 Swagger UI

6.2 cURL 示例

用户注册

用户登录

获取新闻列表

创建新闻

附录

初始分类数据

版本历史

18 KiB

Raw Permalink Blame History

Base Path: `/api/v1/user`

Base Path: `/api/v1/categories`

Base Path: `/api/v1/news`