我做的一个返回用户数据的接口:
{
"user_id":123,
"user_name":"张三",
"school":{
"school_name":"广州第一中学",
"school_type":"中学"
},
"user_address":{
"province":"广东",
"city":"广州"
}
}
《用户接口文档》:
字段名 说明 user_id 用户iduser_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
文章评论