项目导航站需求设计之接口文档

后端 > Java SpringBoot Java
发布时间 :
字数:1.6k 阅读 : 评论:
  1. 一、接口文档设计
    1. 一、用户模块
      1. 1. 用户注册接口
      2. 2. 用户登录接口
      3. 3. 获取当前用户信息
      4. 4. 用户列表（仅管理员）
      5. 5. 用户删除接口（逻辑删除）
    2. 二、 项目导航模块
      1. 1. 获取项目列表接口（首页展示）
      2. 2. 获取项目详情接口
      3. 3. 添加项目接口
      4. 4. 更新项目接口
      5. 5. 删除项目接口
      6. 6. 获取项目管理列表接口（后台管理用）
      7. 7. 点赞项目接口
      8. 8. 检查是否已点赞接口
      9. 9. 记录项目浏览量接口
      10. 10. 添加评论接口
      11. 11. 获取评论列表接口

一、接口文档设计

一、用户模块

1. 用户注册接口

  • 接口地址：POST /api/user/register
  • 请求参数：
{
  "userAccount": "qixiaoran",
  "userPassword": "12345678abc",
  "checkPassword": "12345678abc"
  “userName”: "柒小染"
}
  • 返回结果：
{
  "code": 0,
  "data": 10001,  // 用户ID
  "message": "ok",
  "description": ""
}

2. 用户登录接口

  • 接口地址：POST /api/user/login
  • 请求参数：
{
  "userAccount": "qixiaoran",
  "userPassword": "12345678abc"
}
  • 返回结果：
{
  "code": 0,
  "data": {
    "id": 10001,
    "userName": "柒小染",
    "userAccount": "qixiaoran",
    "avatarUrl": "https://cdn.qixiaoran.com/avatar.png",
    "gender": 0,
    "phone": "13800138000",
    "email": "xran@qq.com",
    "userStatus": 0,
    "createTime": "2024-01-01T10:00:00",
    "userRole": 0
  },
  "message": "ok"
}

3. 获取当前用户信息

  • 接口地址：GET /api/user/current
  • 鉴权：需要登录
  • 返回结果：
{
  "code": 0,
  "data": {
    "id": 10001,
    "userName": "柒小染",
    "userAccount": "qixiaoran",
    "avatarUrl": "https://cdn.qixiaoran.com/avatar.png",
    "gender": 0,
    "phone": "13800138000",
    "email": "xran@qq.com",
    "userStatus": 0,
    "createTime": "2024-01-01T10:00:00",
    "userRole": 0
  },
  "message": "ok"
}

4. 用户列表（仅管理员）

  • 接口地址：GET /api/user/search?userName=
  • 请求参数：
    • UserName: 可选关键词（按昵称搜索）
  • 权限：仅管理员
  • 返回结果（分页形式）：
{
  "code": 0,
  "data": [
    {
    "id": 10001,
    "userName": "柒小染",
    "userAccount": "qixiaoran",
    "avatarUrl": "https://cdn.qixiaoran.com/avatar.png",
    "gender": 0,
    "phone": "13800138000",
    "email": "xran@qq.com",
    "userStatus": 0,
    "createTime": "2024-01-01T10:00:00",
    "userRole": 0
     },
      ...
   ],
  "message": "ok",
  "description": ""
}

5. 用户删除接口（逻辑删除）

  • 接口地址：POST /api/user/delete
  • 权限：仅管理员
  • 请求参数：
{
  "userId": 10001
}
  • 处理逻辑：
    • 将 isDelete = 1
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

二、 项目导航模块

1. 获取项目列表接口（首页展示）

  • 接口地址：GET /api/project/list
  • 请求参数：
{
  "pageSize": 10,
  "pageNum": 1,
}
  • 返回结果：
{
  "code": 0,
  "data": {
    "records": [
        {
        "id": 2,
        "title": "小柒味来",
        "description": "基于 Spring Boot 开.....",
        "content": "项目的定位是一款为餐饮企....",
        "img": "https://qixiaoraxxxeb683b-7345-4463-a6ce-185826861be6.png",
        "href": "https://qi.sky.onavi.icu/",
        "avatar": "https://qixixxxxbac469e-dc62-46f3-8abc-1322238a8510.jpg",
        "userId": 1,
        "sort": 0,
        "status": 0,
        "isCarousel": 1,
        "viewCount": 13,
        "likeCount": 1,
        "commentCount": 3,
        "createTime": "20.....-28T10:56:25.000+00:00",
        "updateTime": "20.....-28T10:56:25.000+00:00"
        }
    ]
    "total": 100，
    "size": 0,
  },
  "message": "ok"
}

2. 获取项目详情接口

  • 接口地址：GET /api/project/detail/{id}
  • 请求参数：路径参数 id
  • 返回结果：
{
  "code": 0,
  "data": {
    "id": 2,
    "title": "小柒味来",
    "description": "基于 Spring Boot 开发的单体.....",
    "content": "项目的定位是一款为餐饮企业（餐厅、饭.....",
    "img": "https://qixiaoran-bu.....b-7345-4463-a6ce-185826861be6.png",
    "href": "https://qi.sky.onavi.icu/",
    "avatar": "https://qixi.......69e-dc62-46f3-8abc-1322238a8510.jpg",
    "userId": 1,
    "sort": 0,
    "status": 0,
    "isCarousel": 1,
    "viewCount": 14,
    "likeCount": 1,
    "commentCount": 3,
    "createTime": "20....-28T10:56:25.000+00:00",
    "updateTime": "2.....-28T10:56:25.000+00:00"
  },
  "message": "ok",
  "description": ""
}

3. 添加项目接口

  • 接口地址：POST /api/project/add
  • 请求参数：
{
  id: undefined,
  title: '',
  description: '',
  content: '',
  img: '',
  href: '',
  avatar: '',
  sort: 0,
  status: 0,
  isCarousel: 0,
}
  • 返回结果：
{
  "code": 0,
  "data": {
    "id": true
  },
  "message": "ok"
}

4. 更新项目接口

  • 接口地址：PUT /api/project/update
  • 请求参数：
{
  id: undefined,
  title: '',
  description: '',
  content: '',
  img: '',
  href: '',
  avatar: '',
  sort: 0,
  status: 0,
  isCarousel: 0,
}
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

5. 删除项目接口

  • 接口地址：POST /api/project/delete
  • 请求参数：
{
    id:"1"
}
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

6. 获取项目管理列表接口（后台管理用）

  • 接口地址：GET /api/project/admin/list
  • 请求参数：
{
  "pageSize": 10,
  "pageNum": 1,
  "title": "小柒味来"
}
  • 返回结果：
{
  "code": 0,
  "data": {
    "records": [
        {
        "id": 2,
        "title": "小柒味来",
        "description": "基于 Spring Boot 开.....",
        "content": "项目的定位是一款为餐饮企....",
        "img": "https://qixiaoraxxxeb683b-7345-4463-a6ce-185826861be6.png",
        "href": "https://qi.sky.onavi.icu/",
        "avatar": "https://qixixxxxbac469e-dc62-46f3-8abc-1322238a8510.jpg",
        "userId": 1,
        "sort": 0,
        "status": 0,
        "isCarousel": 1,
        "viewCount": 13,
        "likeCount": 1,
        "commentCount": 3,
        "createTime": "20.....-28T10:56:25.000+00:00",
        "updateTime": "20.....-28T10:56:25.000+00:00"
        }
    ]
    "total": 100，
    "size": 0,
  },
  "message": "ok"
}

7. 点赞项目接口

  • 接口地址：POST /api/project/like/{id}
  • 请求参数：路径参数 id
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

8. 检查是否已点赞接口

  • 接口地址：GET /api/project/like/check/{id}
  • 请求参数：路径参数 id
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

9. 记录项目浏览量接口

  • 接口地址：POST /api/project/view/{id}
  • 请求参数：路径参数 id
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

10. 添加评论接口

  • 接口地址：POST /api/comment/add
  • 请求参数：
{
  "projectId": 1,
  "content": "评论内容",
  "parentId": 0
}
  • 返回结果：
{
  "code": 0,
  "data": true,
  "message": "ok"
}

11. 获取评论列表接口

  • 接口地址：GET /api/comment/list/{projectId}
  • 请求参数：路径参数 projectId
  • 返回结果：
{
  "code": 0,
  "data": [
    {
    avatarUrl: "https://qixiaoran-bxxxx22238a8510.jpg"
    content: "test"
    createTime: "20xx-29T06:43:54.000+00:00"
    id: 1
    isDelete: 0
    likeCount: 0
    parentId: 0
    projectId: 2
    status: 0
    updateTime: "20xx-29T06:43:54.000+00:00"
    userId: 1
    userName: "admin"
    }
  ],
  "message": "ok"
}
欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1701220998@qq.com

闽ICP备2025086430号 ©2023-2025 QiXiaoRanTuT

Built with Hexo and 3-hexo theme

导航页 GitHub