嘟嘟社区

前端工程师这个要求是否合理之二 :文档的问题


本帖最后由 gdtv 于 2022-5-2 21:28 编辑

我做的一个返回用户数据的接口:

{
        "user_id":123,
        "user_name":"张三",
        "school":{
                "school_name":"广州第一中学",
                "school_type":"中学"
        },
        "user_address":{
                "province":"广东",
                "city":"广州"
        }
}

《用户接口文档》:

字段名 说明
user_id 用户id
user_name 姓名
school 学校数据结构
user_address 地址数据结构

因为多个接口都用到school和user_address,所以我把他们写到一个单独的《接口通用数据说明文档》:

school学校数据结构:

字段名 说明
school_name 学校名称
school_type 学校类型

user_address地址数据结构:

字段名 说明
province 省份
city 城市

前端工程师的吐槽:

我打开《用户接口文档》看,然后还要再打开《接口通用数据说明文档》去找对应的字段,太麻烦了,你能不能把"学校数据结构"和"地址数据结构"都写到《用户接口文档》里?

请教一下,你们是怎么写文档的呢?

————————————-

前端工程师这个要求是否合理之一: https://hostloc.com/forum.php?mod=viewthread&tid=1010810

你们没经理吗? 拉着前端找经理开会 让经理订
这种情况是开发之间看的文档,就用markdown和swagger呗,一个可以双向引用一个支持json和在线测试。
你跟前端至少要辞一个,不过我建议先把项目经理辞了。
你们项目没项目经理吗? 有问题不问领导,在这问有毛用。。。
看数据结构复不复杂喽 根据实际情况看要不要分文档
文档 双向引用 的作用
你两打一架,打完就知道谁迁就谁了

喵酱暗恋我 发表于 2022-5-2 21:51
你们没经理吗? 拉着前端找经理开会 让经理订

好方法

optimism