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

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

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

我 产生了迷茫

再者

前端的大佬们

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

[evan1]

后端，每个字段都有。这是基本的要求。

[v21984]

枚举值的加注释，有多个某 id 的加注释，其它不加

[linuxsuren]

乱入下我的开源接口工具 https://github.com/LinuxSuRen/api-testing

[wogogoing]

不是在代码层面写好注释然后生成 swagger 文档吗？

[imdong]

不写注释鬼知道这个字段是干嘛的，到时候猜错了出 BUG ，是你改还是前端改？

每个字段最少提供一个与前端对应的名称注释，是否必填，数据类型（格式要求），如果是枚举，则提供每个选项的值与对应说明或获取来源。

如果这个结构在其他接口出现过，我会标明该字段内结构与注释以某接口的某字段下结构为准，

例如 forumReplyList 字段下数据，我会标注为 数组内结构为 forumReply{}，以接口 /reply/view 的同名结构为准，我在那个接口会明确指定该结构的名称。

[zbw0414]

先用大模型帮我构建一个基础的结构出来，比如根据代码或者 swagger 直接生成完整的文档，再把关键逻辑字段、易混淆的字段自己关注完善一下就行了。这种文档属于那种绝大部分都是废话，见文知意的；但是个别的字段确实比较绕需要特别说明的。如果你没有文档或者写的不细，那到时候真出了问题可能就是你背锅了；但是每个字段都打字又纯属体力活，所以分清主次，善用 AI 就好了。

[taoyuanming]

如果你是前端，后端只给了不清不楚的返回示例，估计你更迷茫

[fyxtc]

自己开发如果你有把握保证字段名清晰明了就可以不用写
比如 user_id 谁都知道是啥
但是 is_delete 对于三个月后的你就丈二和尚了

所以如果是多人协作，保证每个字段清晰注释是必要的，因为你无法保证每个字段命名都能让别人看得懂，而且这种只要写一遍就能让所有人受益（包括你自己），也是基本素养。

[q1102389095]

部分主要逻辑写注释至于枚举因为模型定义有替换成中文的方法所以也没什么注释，看是合作开发还是自己开发了，自己怎么舒服怎么来，合作基础的语法不用其他该写就写

[lvlongxiang199]

`is_can_submit` 这个命名方式好奇怪啊

[mango777]

你的看字段名就知道含义，你同事的像是在告诉你 1+1=2 、这是鼠标、这是显示器，这种层次

[mango777]

要么就备注在类里，用 swagger 显示字段含义

[XCFOX]

接口用的 GraphQL ，代码里会写详细的字段注释，再用框架生成 GraphQL Schema 。前端直接用 GraphQL Schema 生成接口 SDK ，确保端对端类型安全。

[pollux]

@wogogoing @zbw0414 swagger +1 ，就喜欢用 fastapi / robyn 这种带有 openapi/swagger 文档输出的，简洁明了还能直接在线测试

[Akkuman]

openapi

[kneo]

文档有很多方式，不一定通过注释的方式。一边来说数据清楚是不需要每个字段都注释的。
而“希望我写的清楚一点 标清楚每个字段的含义”这种建议也缺乏指引，哪个字段有什么歧义需要具体指出来。一句“写详细点”犯了和“文档不详细”一样的错误。

比如：

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 的时区是什么？

[blackmatch]

既然是接口文档，我建议是不要用代码注释的方式去解释字段，而是分开来写，代码只是一个返回示例即可；另外是否需要每个字段都解释具体还得看场景，如果是公司内部前后端协作，有个固定的风格习惯后，一些通用字段（比如 id 、total ）可以不用每个接口都解释，如果是公开 API 或者交付给外部的 API 越详细越好。

[CyouYamato]

让 AI 加上注释又不需要花你多少时间.

[ty29022]

我不能接受 childs

[Gilfoyle26]

后端：什么是注释？？？

[ns09005264]

为什么你们的接口文档是这样的，更方便的做法难道不是使用 API 文档生成库，然后在入参和返回的结构体上添加注释吗？最后项目启动后可以在线浏览详细的接口文档，包含每个字段所需的类型、注释说明、参考值等，还能直接调用 API 测试。
参考: https://petstore.swagger.io/#/

[z1829909]

has_more_page 这个参数需要返回吗, 前端根据 current total size 不是可以算出来么.

[issakchill]

每个字段都有注释 然后生成文档的时候自动生成的

[sunfall]

@ty29022 以前用过 datas

[wolfie]

这啥也没有啊。。。你们前端这么软吗。
字段名、数据类型、值大小范围、必填、校验规则、特殊场景描述。

[Ackvincent]

后端代码中无所谓，但是接口要有详细的文档说明。

[qiniu2025]

不满意，让 AI 重新按你的要求加上注释即可，2025 年了该告别刀耕火种了

[61366756]

代码中不允许注释

[chenjk]

第一天上班啊，让你写注释都这么难受😢

[dcdlove]

应该 给 model 每一个字段 标注出说明和枚举项的说明 和字段作用意图 ，并且在每个控制器和每个暴露接口中注明用法示例 和详细说明可能出现的错误说明等，并且输出标注规范的 swagger

[fredweili]

注释的活，copilot 之类的能做的很好了，就是打个//然后等几秒

[clf]

我们是所有 bean 类（包括给前端的和后端的）要求写注释，然后写了一个 idea 的插件去根据注释生成接口文档……
如果注释没写，常见的字段也有一些内置词典……同个代码文件里的 api 字段，如果遇到了别的接口上已经写的，会将其作为字典来用。
---
但至少得详细说明接口是干嘛的，每个字段是干嘛的。

[cccssss]

"type": "in_select"如果就只有 in select 一个选择的话，你不写注释倒也行。但是你敢发誓只有 in select 一个值？

[cslive]

这写的啥啊，除了知道返回的字段，其他啥都看不出来

[DIO]

贴出来代码块，下面列表解释喽。如果要团队协作，肯定需要一种大家都能接受的方式

[wxshuai]

使用 api 工具类似于 swagger 能在模型层定义字段信息，很清晰 明了

[isnullstring]

不是 代码里注释，生成 swagger 么？

对自己、对其他人、对前端都能统一概念

[kk2syc]

除了统一返回字段，每个接口的自有数据都要写好数据字典

[zzzzero]

不写，返回给前端猜，前端也是给 AI 猜。猜的还真准。

[MuXia]

要明确的划分责任的话，建议是写清楚，这样出问题 可以迂回一下，虽然最终可能还是要改代码，但不会没理

[Lynntox]

不写清楚 还要去猜看着都恼火

[HojiOShi]

我给我自己的程序写的注释都不会这么潦草，鉴定为十足的水货。

[ZENGQH]

正好最近对接用友，他们的接口文档还算比较正规
https://open.yonyoucloud.com/#/doc-center/docDes/api?apiId=1858257166049738757&from=&isOrigin=1&selectApiTab=open

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

[ZENGQH]

一般都写这种 hh

[flowerains]

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

自己如果是内部对接，有个 json 格式文档就够了

[Bearst]

写到自己能看懂，但是别人看不懂的地步

[fengpan567]

json 里写注释干啥，不直接用 swagger 吗

[iScout]

测试看到这样的接口文档直接打回

[ayase252]

文档就是后端和前端在签合同，合同写这样你能签？

[kristofer]

你在钓鱼吗🎣？

[securityCoding]

日常全部是 pb 了，舒服~

[jamesjammy061]

去年已经是丢给 ai 写的程度了🤣

[VchentozV]

@zbw0414 珍爱生命

[abc0123xyz]

写那种防御性编程（ dog ）

[jackbon]

给别人看的文档必须详细。自己看的文档自己知道就行 不写也行。