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

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

• 请不要在回答技术问题时复制粘贴 AI 生成的内容

如题

这是组内另一个同事写的

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

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

我产生了迷茫

再者

前端的大佬们

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

接口文档

注释

规范

56 条回复 • 2025-03-02 20:05:54 +08:00

evan1

31 天前 via iPhone

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

v21984

31 天前 via Android

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

linuxsuren

31 天前

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

wogogoing

31 天前 via iPhone

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

imdong

31 天前 via iPhone

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

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

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

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

zbw0414

31 天前

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

taoyuanming

31 天前

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

fyxtc

31 天前

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

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

FlorentinoAriza

31 天前

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

lvlongxiang199

31 天前

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

mango777

31 天前

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

mango777

31 天前

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

XCFOX

31 天前

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

pollux

31 天前

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

Akkuman

31 天前 via Android

openapi

kneo

31 天前

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

比如：

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

31 天前

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

CyouYamato

31 天前

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

ty29022

31 天前 via iPhone

我不能接受 childs

Gilfoyle26

31 天前

后端：什么是注释？？？

ns09005264

31 天前

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

z1829909

31 天前

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

issakchill

30 天前

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

sunfall

30 天前

@ty29022 以前用过 datas

wolfie

30 天前

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

Ackvincent

30 天前

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

qiniu2025

30 天前

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

61366756

30 天前

代码中不允许注释

chenjk

30 天前 via iPhone

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

dcdlove

30 天前

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

fredweili

30 天前

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

clf

30 天前

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

cccssss

30 天前

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

cslive

30 天前

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

DIO

30 天前

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

wxshuai

30 天前

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

isnullstring

30 天前

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

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

kk2syc

30 天前

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

zzzzero

30 天前

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

MuXia

30 天前

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

Lynntox

30 天前

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

HojiOShi

30 天前

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

ZENGQH

30 天前

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

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

ZENGQH

30 天前