后端的大佬们 你们的接口文档注释写道什么程度呀

241 天前
 puzzle9

如题

这是组内另一个同事写的

{
    "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": "金莹"
                }
            ]
        }
    ]
}

然后嘛 组内的一个前端 希望我写的清楚一点 标清楚每个字段的含义

我 产生了迷茫

再者

前端的大佬们

你们心中的接口文档是咋样的

6412 次点击
所在节点    程序员
56 条回复
Lynntox
239 天前
不写清楚 还要去猜看着都恼火
HojiOShi
239 天前
我给我自己的程序写的注释都不会这么潦草,鉴定为十足的水货。
ZENGQH
239 天前
正好最近对接用友,他们的接口文档还算比较正规
https://open.yonyoucloud.com/#/doc-center/docDes/api?apiId=1858257166049738757&from=&isOrigin=1&selectApiTab=open

swagger 只适合内部交流对接使用 一般需要文档形式留存档案 以防止前后端变动导致接口报错
ZENGQH
239 天前

一般都写这种 hh
flowerains
239 天前
如果是我们交付给第三方用的,一般都是转么写的接口文档,用 markdown 写,每个字段和类型和枚举都要写清楚。

自己如果是内部对接,有个 json 格式文档就够了
Bearst
239 天前
写到自己能看懂,但是别人看不懂的地步
fengpan567
239 天前
json 里写注释干啥,不直接用 swagger 吗
iScout
239 天前
测试看到这样的接口文档直接打回
ayase252
239 天前
文档就是后端和前端在签合同,合同写这样你能签?
kristofer
239 天前
你在钓鱼吗🎣?
securityCoding
239 天前
日常全部是 pb 了,舒服~
jamesjammy061
239 天前
去年已经是丢给 ai 写的程度了🤣
1Z3KYa0qBLvei98o
239 天前
@zbw0414 珍爱生命
abc0123xyz
239 天前
写那种防御性编程( dog )
jackbon
238 天前
给别人看的文档必须详细。自己看的文档自己知道就行 不写也行。
goldenAndGreen
233 天前
json schema 定义好,懒得写可以让 cursor 什么的生成

这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/1113551

V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX