前后端日常吵架——接口文档谁来定义呢？

和朋友聊天，他说他们公司开始了一个新项目，由他负责后端开发。因为之前做过全栈的项目，前后端开发思路都懂，就自己把逻辑走了一遍，写了api接口。结果项目开发到一半，新招了个ios，上来就说他写的接口不行吵了起来。

那么接口文档到底是该谁来定义呢？

接口是什么？

API，全称是ApplicationProgramming Interface，即应用程序编程接口，我们日常中习惯简称为“接口”。接口是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

接口有什么用？

在平时的开发过程中，前后端经常会进行数据交互，那么在前后端分离的项目中，前端就不用管后台的工作，用api调取数据即可。

接口文档该由谁来写呢？

笔者认为一般接口文档一定是后端来写，只是我们要事先要和前端商量定义，然后再编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
通俗一点就是：客户端出接口需求，服务端出接口方案。

为什么要写接口文档？

1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发；
2、项目维护中或者项目人员更迭，方便后期人员查看、维护；

接口规范是什么？

首先接口分为四部分：方法、url、请求参数、返回参数
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)；
2、url：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开；
3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填；
4、返回参数结构可以有一个结构体也可以有多个结构体；

如何自动生成文档？

最简单的是找一个合适的工具，省去敲字对格式的痛苦。这里推荐的是Eolinker，一个适合不同规模开发团队的在线API文档工具。而且除了文档部分的功能外，整个API开发流程的不同阶段，都可以直接在Eolinker上进行，省事。

当然还有其他类似的平台也可以满足在线编辑规范接口的平台：apidoc，sosoapi等
使用地址：www.eolinker.com