API 示例文件

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -0,0 +1,94 @@
+# API-DOC
+
+> 集中前后端 api
+
+## 维护成员须知
+
+### 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
+{
+  "res": 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** - 更新时间
+```

api/Auth-权限.md

@@ -0,0 +1,92 @@
+# Auth - 权限
+
+> url 前缀：**auth**
+>
+> 示例：**https://xxxxxxxxx/api/auth/xxxx**
+
+## 获得当前登录用户的信息
+
+```http
+get /current
+```
+
+### Response
+
+```ts
+interface UserData {
+  err: 0 | 401 /* 用户信息失效 */;
+  res: UserSerializer;
+}
+```
+
+see [UserSerializer](../serializer/UserSerializer.md)
+
+## 登录
+
+```http
+post /login
+```
+
+### Parameters
+
+```ts
+interface loginDTO {
+  username: string;
+  password: string;
+}
+```
+
+### Response
+
+```ts
+interface UserData {
+  err: 0 | 403 /* 用户名密码错 */;
+  res: UserSerializer;
+}
+```
+
+see [UserSerializer](../serializer/UserSerializer.md)
+
+## 手机验证码
+
+```http
+post /verification
+```
+
+### Parameters
+
+```ts
+interface VerificationDTO {
+  phoneNumber: string;
+  token: string;
+}
+```
+
+## 注册
+
+```http
+post /register
+```
+
+### Parameters
+
+```ts
+interface RegisterDTO {
+  username: string;
+  password: string;
+  phoneNumber: string;
+  token: string;
+  email: string;
+}
+```
+
+### Response
+
+```ts
+interface UserData {
+  err: 0 | 400;
+  res: UserSerializer;
+}
+```
+
+see [UserSerializer](../serializer/UserSerializer.md)

serializer/CodeSerializer.md

@@ -0,0 +1,23 @@
+# CodeSerializer
+
+代码信息
+
+## Attributes
+
+```ts
+interface CodeSerializer {
+  examId: number;
+  fetchAt: LocalDateTime;
+  startAt: LocalDateTime;
+  endAt: LocalDateTime;
+  codeList: Array<NestedCodeItemVO>;
+}
+
+interface NestedCodeItemVO {
+  questionId: number;
+  language: string;
+  projectName: string;
+  editable: Map<String, String>;
+  uneditable: Map<String, String>;
+}
+```