API-DOC

API-DOC

集中前后端 api

维护成员须知

api 规范

前缀与规范

1. 所有后端 api 务必至少添加前缀：/api
2. restful 规范， 以数据为中心，每个数据 务必 返回 id
3. 所有返回值均为 对象 ，禁止 使用 bool string array 等类型作为 json 返回值

数据定义

1. serializer 中说明数据格式

api 文件命名

[模块英文命名]-[解释].md

example: User-用户.md

api 文件内容结构

# 命名

> url 前缀：**user**
>
> 示例：**https://xxxxxxxxx/api/user/xxxx**

## 请求名称

⬇️ 为路径参数格式 :userId 表示变量

```http
post /:userId
```

### Parameters

⬇️ 为 post body 中的参数格式

```json
{
  "nickname": "nickname",
  "avatar": "xxxxxxxxxx",
  "bio": "小白白白白白白白白白白白"
}
```

⬇️ 为问号传参格式 example： user?userId=1

| Name   | Type   | Description        |
| ------ | ------ | ------------------ |
| userId | number | 查看用户的所有 tag |

### Response

```json
{
  "res": UserSerializer
}
```

see [UserSerializer](./user/serializer/UserSerializer.md)

## 请求名称

etc...

serializer 文件结构

example

# UserSerializer

用户的基本信息

## Attributes

- id : **Number** - 用户 id
- role : **String** - 身份类型 [ STUDENT - 学生用户, TEACHER - 教师用户]
- username : **String** - 用户名
- nickname : **String** - 昵称
- bio : **String **- 用户自我描述
- avatar : **String** - 头像 URL
- createdAt : **String** - 创建时间
- updatedAt : **String** - 更新时间