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

Question

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

Answer 1

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

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

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

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

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

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

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

Answer 2

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

Answer 3

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

Answer 4

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

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