web项目开发，先让后端程序员产出接口文档，是否是开发流程最合理的选择？有无更好选择？利弊是什么？

Question

求大家对开发流程的看法。
是不是后端程序员一般会认为先给接口文档，是对自己不利？

Answer 1

对这方面我的经验也不多，我觉得主要看你们前后端的开发进度，就以我自身管理的项目为例，来说说我的看法。

目前在做的项目是某知名旅游网站的一个小外包项目，采用前后端分离的开发模式，前端React+dva，后端基于SpringBoot框架提供Restful接口，项目周期短，时间紧，拿到需求之后，做出UI设计和数据库设计，前端就开始干活了。在都没有深入挖掘需求之前，前端在做某个功能点的时其实更清楚他需要什么接口，传递什么数据。所以我认为这种情况下，前端提供接口需求是合理的。

至于产出接口文档，我认为这应该是一个持续性而且易于维护的工作，我们用到了Swagger ui，后端通过一些注释规则和简单的配置就可以生成接口文档，前端可以通过web端页面实时的看到接口的变化，前端或者QA团队也可以通过web端页面做接口在线测试，减少了沟通成本。而后端根据接口变化，只需要维护注释，接口文档就可以自动生成并支持导出，减少了维护成本。

总体来说，我的做法是前端提供接口需求，后端生成接口文档。

PS.刚注册账号，处女答送给你了，可能比较拙劣，但是希望对你有所启发。

Answer 2

使用swagger自动生成API文档，还可以直接测试API的正确性。
如下：

好用、简单、不扯皮

Answer 3

接口文档是要必须要有的，现在前端开发可以自己使用假数据模拟出界面的各种情况，所以提前约定好接口格式之后，前端就可以通过模拟的方式独立开发，而不需要等到后端接口开发完成之后才能进行动态网页部分的开发。

接口文档产出现在也可以自动化了，我们团队现在用的是：swagger，后端可以在和前端约定好接口格式之后，定义好需要的接口之后，通过工具自动生成。

接口格式的定义参考：RESTful API

另外还有一些接口管理平台，可以用来管理接口，比如：

• RAP
• easy-mock
• apidoc

Answer 4

从我近年来的经历来看，让后台写接口文档好，当然是前端基本没有后台经验的前提下；
后台写的好处：
理由1:在前后台开发人数差不多的时候，后台的开发一般都要比前端开发快，让他们去规定接口和写文档，时间分配的相对合理；
理由2:前端自己命名，出现接口命名的不规范的几率很大（一般接口的名字跟数据里表的名字比较接近），这样容易造成重复返工，影响前后台的工作效率；
理由3:作为一个前端的我，很乐意看接口文档，不用自己费脑细胞去想接口名字和形式；

前台写的好处：
理由1:（在不考虑后台的书写格式情况下）前端可以随心地写接口命名；
理由2:现在的前端都可以建假数据，可以把一些后台的事给做了，这个时候后台只要根据前端写的接口去操作就好了，目前前端自己创建假数据的情况比较普遍；

一般的流程都是，后台看ui设计稿，先搞数据库需要那些字段，再去根据要求哪些请求写对应接口，再将接口文档给前端，前端再实际需求将哪些后台没有的接口补上。

特殊情况：前端人数比后台多，且前端具有后台经验。这样让他们去写接口，可以避免接口命名规范问题同时也可以一次性将前端需要的接口告诉后台，后台也就不用重复去补遗漏的接口；

Answer 5

看具体项目。前端开发先空着需要接口的部分也行，毕竟连这段代码不需要花多长时间，时间主要用在与开发人员联调上。别人没开发好，你也没法联调。
当然好的方式是先定义好接口，形成文档，大家都并行开发，按这个是理想化的情况，是拥有好的开发流程的公司，优秀的开发团队及成员的前提下才能做到的。一些中小企业，特别是互联网公司，需求，设计频繁改动很难做到API不改动。

API可以用下Swagger， 自动生成api文档。 及时更新与联调

Answer 6

是不是后端程序员一般会认为先给接口文档，是对自己不利？

不是。

但是，大部分程序员不善于写文档，自动把注释跑一下，就叫文档啦？

流程的东西是根据实际情况来的嘛，想清楚要解决什么问题，想清楚各方需要什么最重要。

Answer 7

1、如果后端工程师对于整块业务较为熟悉的话，并且前端经验不是很足时，由后端产出接口文档是较为合适的；
2、正常情况都是前后端沟通之后，前端需要什么数据，后端能提供什么，这样商讨之后再行产出接口文档是较为合适的；