# API-DOC

> 集中前后端 api

## 维护成员须知

### 文件夹管理须知

1. 每个后端负责人创建并维护自己的文件夹
2. 每个前端负责人协助维护各自负责的文件夹

### 文件结构管理须知

#### 每个小组文件夹下 **建议** 有

1. README 声明负责人
2. api 文件夹 （用于存放所有 api）
3. serializer 文件夹 （用于存放所有 api 中提到的对象  细则）

#### example：

```
user
├── README.md
├── api
│   └── User-用户.md
└── serializer
    └── UserSerializer.md
```

### api 规范

#### 前缀与规范

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

#### 数据定义

1. serializer 中说明数据格式

#### api 文件命名

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

example: User-用户.md

#### api 文件内容结构

````markdown
# 命名

> 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
{
  "data": UserSerializer
}
```

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

## 请求名称

etc...

````

## serializer文件结构

example
```md
# UserSerializer

用户的基本信息

## Attributes

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