java人员请回答,接口文档的编写和提供时机?

我的神
  • 966

项目开发周期,你们什么时期会给前端写接口文档,怎么写接口文档,为什么?
或者干脆不写,或者写个废的,为什么?
请你谈谈你过去工作在接口文档方面是怎么干的。多谢。

回复
阅读 1.6k
4 个回答

文档烂的原因可以有很多,从环境不行到管理不行到人不行工具不行,每个环节都可以把文档搞个稀巴烂。

但要说不写文档爽不爽,作为后端我可以告诉你主要就看前端和技术管理。

前端要是天天来问接口怎么对接,那我肯定是想办法整一个自动生成的文档,哪怕是自己写。(其实现在的文档工具就是我自己写的protoc插件)。

但是但是,如果前端是那种闷葫芦,对接口的时候有问题都憋着不说,处理了接口问题也不反馈;又或者从不看文档的,给他发个文档链接还能继续问东问西问文档里都写了的东西;

遇到这样的队友,那后端对文档也肯定是敷衍了事,毕竟没人会欣赏你想了半天设计出来的接口,这就是环境,大家都在混,你做得好做不好都没反馈,那你工作起来也没劲。

技术管理就更不用说了,如果用文档自动工具再结合强制code review,做好CI检查,规范开发流程,先定接口再实现,那不管后端开发人怎么样,至少在制度下产出的东西会有个底线。

不过这样的环境肯定会更压抑...所以也不能一味说加强制度就行,只能说文档或文档代表的项目质量是要在多个维度去权衡利弊的。在制度合理执行适度的情况下大家能吃到质量提高的红利,少加班,干活快又稳,也不用天天和队友撕逼或者骂管理傻逼。

应该是后端先出文档,再根据文档写代码,但是现实更多的是先写完代码再出文档,写完代码再写接口文档真的不想写。不过我司现在用的是apidoc,写完代码写好注释文档自动生成,不知道其它公司怎么做的。

后端开始接口前确定api输入输出 返回数据可以用mock 这样前后端可以并行开发

  • 2
新手上路,请多包涵

前公司的开发流程是这样的,前后端工作效率极高,可供借鉴。

1)需求评审后,前后端进行详细设计,编写详细设计文档(包含后端接口)
2)进行详细设计评审,前端在评审会上如果对接口有异议,可以提出,再让后端修改,直至双方都认可
3)前后端根据之前协商的接口文档各自开发,最终进行调试

宣传栏