以api文档为中心--前后端分开发离新思维

api文档编写好像很简单，其实不是。
一个良好的api文档，需要就有以下内容：
接口详细描述，接口参数详细描述，接口返回结果详细描述，容易理解的范例。这些内容其实是不少的，编写过程中还非常单调乏味。再加上项目紧张，积压的未编写api文档太多等等因素，造成了现实工作中，大部分api文档都是残缺不全的状况。从结果上看，编写api文档并不简单。

api文档编写好像只是后端工程师一个人的事情，其实不应该是。
实际工作中，api文档都是由实现这个api的后端工程师根据api来编写的。因为api是某人开发的，他知道最清楚，api文档就应该是这个人来写。大家都是这么理所当然的认为。但是这个接口不是后端工程师无中生有自己造出来的，而是大家根据需求讨论确定的。这个接口的功能、请求参数、返回结果，都是根据需求来确定的。不止和后端工程师关系密切，和产品人员、经理、前端人员都有关系，后来者也要根据这些api文档来工作。因此api文档编写不只是后端工程师一个人的事情。

api文档不要一个人完成，这样他的负担会很重，尤其是后端开发人员。我们应该是这样做：产品新建接口，填写部分内容，主要是接口名称和描述；后端开发人员编写接口的url、接口参数和返回字段；前端人员参与确定和编写部分api文档内容；技术经理从全局角度审查和编写部分api文档。

api文档应该尽早编写。
api文档是前后端开发人员协作的依据。没有api文档，前端开发人员就无法进行开发，项目也就无法推进。
传统的做法是：大家一起开需求会；开完需求会议后，后端开发人员花一段时间实现接口；为了让前端人员能尽快使用接口，后端开发人员会尽快简单编写一下api文档，再通知前端开发；前端开发人员再按照api文档开发程序，绑定数据；最后前后端人员一起联调。
这样单向的，一步一步依次执行的工作模式，像链条一节连着一节。即使其中某一个人工作高效，完成迅速，也难以加快项目整体的进度；相反，只要其中一个环节卡住了，整个项目也就停止了，上线变成不可能。总的结果是，让项目难以快速完成，上线时间非常紧张。
参与项目开发的所有都感觉到了这一模式的缺陷。

我们应该以api文档为中心展开工作。
首先，需要改进工序。
一，产品人员在调研需求，完成原型之后，应该整理一下每个页面，每个功能大概需要哪些接口，新建api文档，填写部分内容，包括接口名称，接口描述，返回的结果字段描述。
二，召集所有人员参加需求会，讲解需求，分配模块开发人员，讨论接口文档中哪些可以当场确定。
三，负责相同模块的前后端人员一起讨论，根据已经创建的api文档，确定api的url，请求参数名称，返回结果字段名称，完善好api文档；api文档的所有内容都应该完全确定，如果有疑问，应该找产品人员和经理一起确定。
四，前后端人员严格依照api文档各自开发，如果开发过程中有变动，一定要通知对方，并且修改api文档。这样两人同时进行开发，实现了并行工作，比老的api和文档完成后再做前端节约了大量时间。
五，前后端人员实现功能后进行联调，如果出现分歧，应该以api文档为基准。

以api文档为中心，尽快确定api文档和详细参数及结果，尽早完善文档，还有利于新人接收。新接手人参照完善的api文档，可以更快的熟悉项目，尽早完成任务。