后端的大佬们 你们的接口文档注释写道什么程度呀?
这是组内另一个同事写的：
{
"code": 200,
"data": {
"forum": {
"forum_id": 1, //帖子 ID
"user_id": 2, //发帖人 ID
"content": "仅支持文本输入，简体中文、数字、大小写字母，中英文标点符号", //帖子内容
"created_at": "2024-12-12 16:28", //发帖时间
"user_name": "教师", //发帖人名称
"avatar": "http://127.0.0.1:8000/assets/img/teacher_avatar_default.png" //发帖人头像
},
"forumReplyList": {
"data": [
{
"forum_reply_id": 15, //回复内容 ID
"forum_id": 1, //帖子 ID
"user_id": 2, //回复用户 ID
"content": "又一次回复内容", //回复的内容
"created_at": "2024-12-14 22:54", //回复的时间
"forum_reply_like_count": 0, //回复的点赞
"user_name": "教师", //回复用户的名称
"avatar": "http://127.0.0.1:8000/assets/img/teacher_avatar_default.png", //回复用户的头像
"reply_user_name": "教师", //被回复的用户名
"is_delete": true, //是否是当前用户的回复：true 是当前用户的回复可以删除，false 不是当前用户的回复不能删除
"is_like": false //当前用户是否点赞，true 已点赞 false 未点赞
}
],
"current": 1, //当前页
"total": 12, //总共的数量
"size": 10, //当前分页数量
"has_more_page": true //是否有下一页：true 有下一页 false 没有下一页
}
}
}
这是我写的 完全无注释
{
"code": 200,
"data": {
"id": 2,
"type": "in_select",
"question_description": "请选择青龙还是白虎",
"question_images": [],
"question_options": [
{
"description": "青龙",
"image": null
},
{
"description": "白虎",
"image": null
}
],
"student_answer_exists": true,
"is_can_submit": false,
"socket_name": "course_interact_1_2"
}
}
{
"code": 200,
"data": [
{
"id": 2,
"body": "顶层",
"user_type": "teacher",
"user_nickname": "教师昵称阿",
"user_avatar": "http://127.0.0.1:8000/assets/img/teacher_avatar_default.png",
"created_at": "2025-01-07 20:19:38",
"childs": [
{
"id": 6,
"body": "回复 1 的回复 2",
"user_type": "student",
"user_nickname": "程凤英",
"user_avatar": "http://127.0.0.1:8000/assets/img/student_avatar_default.png",
"created_at": "2025-01-07 20:20:15",
"reply_user_nickname": "金莹"
},
{
"id": 5,
"body": "回复 1 的回复 1",
"user_type": "teacher",
"user_nickname": "安智渊",
"user_avatar": "http://127.0.0.1:8000/assets/img/teacher_avatar_default.png",
"created_at": "2025-01-07 20:20:12",
"reply_user_nickname": "金莹"
}
]
}
]
}
然后嘛组内的一个前端 ,希望我写的清楚一点, 标清楚每个字段的含义。我 产生了迷茫，再者，前端的大佬们，你们心中的接口文档是咋样的？
闽公网安备 35020302035485号
而“希望我写的清楚一点 标清楚每个字段的含义”这种建议也缺乏指引，哪个字段有什么歧义需要具体指出来。一句“写详细点”犯了和“文档不详细”一样的错误。
比如：
type 除了 in_select 还有什么值？
question_images 为什么是空的？为什么是个数组？正常应该放几个 image ？
options 的 image 为什么是 null ，支持的格式是什么？
什么叫 student_answer_exists ？是和别的学生的答案冲突的意思？
is_can_submit 是什么意思？什么情况会是 false ？
socket_name 是什么意思？
id 为什么选择 2 ？是全局唯一的吗？如果是全局唯一的为什么不选择一个很大的数字做例子？如果会话内的序列为什么不是从 1 或者 0 开始？
什么是“回复 1 的回复 2”？ id 为 2 的回复是回复 1 吗？
金莹是谁？是 id 为 2 ，user_nickname 为"教师昵称阿"的 nickname ？
created_at 的时区是什么？