API是连接客户端和服务端的桥梁，对于前后端工程师来说，清晰、准确的API文档极其重要，那我们该如何书写规范准确的API文档呢？网易前端工程师包勇明将教你如何书写规范的API文档。

API是什么

API（Application Programming Interface）即应用程序编程接口，是一些预先定义的函数，是连接客户端与服务端的桥梁，可以为应用程序与开发人员提供基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

用过网易云音乐的同学都知道网易云音乐的每日推荐功能，每日推荐功能被业内普遍称赞为精准，甚至被很多网友说比男/女朋友更懂自己。

在iPhone、Web、Mac等所有客户端上都有每日推荐功能，每个客户端上显示的内容都是一样的，它们都在调用同一个API接口，比方说它的地址是/api/discovery/recommend/songs。由于服务器host地址在不同的环境中并不相同，所以在定义接口的时候host地址无需定义。

在定义接口时需要定义请求和响应参数，包括参数名称、类型、描述等信息，比如对于网易云音乐每日推荐的API来说，只需要定义一个请求参数，即需要获取多少条数据，参数可以有默认值，比如设置为20条；同时，还需要定义接口的响应参数，比如响应参数由code、message以及data三个字段构成，使用什么字段可以由技术团队自己决定。

API接口我们知道该如何定义了，那API的文档形式又有哪些呢？

API文档形式

对于前后端工程师来说，维护清晰、准确的API文档非常重要。

上图Word编写的API文档，由于没有统一的规范标准，不同人员对该文档有不同的定义。

IM、Email、Doc、Txt、Wiki、Confluence等都非常不适合编写API文档，这些都不是专业的API管理工具。因为每个人写得文档样式不一样，而且有人写得详细，有人写得简单，这就导致了API文档格式的混乱，容易产生歧义。

Swagger、API Blueprint等有特定语法规范的API书写工具的出现，解决了部分API文档书写问题，很多集成开发环境（IDE）也有插件支持。但它们毕竟不是文档，不够直观，而且存放、管理、维护以及协作成本相对较高。

NEI接口管理平台

NEI虽然叫接口管理平台，但其实不只是管理接口，它可以管理整个产品，也具备项目脚手架的功能，同时具备接口规范、团队协作、工程规范、构建工具、接口MOCK、接口测试等六大功能。

与传统的API接口文档相比，NEI接口文档具有格式统一、便于团队协作、支持自动化工具以及强大的辅助功能等优点。

团队协作：在NEI中，团队协作有成员角色、消息系统、历史动态三部分。成员角色包括开发者、测试者、观察者、管理者以及审核者；消息系统包括系统的消息、泡泡通知等；历史动态包括所有接口的操作，比如参数字段的增、删、改等等。

自动化工具：有了接口规范，我们就可以使用自动化工具在本地生成Mock数据文件，利用Node.js在本地搭建一个服务器，这样客户端开发人员就可以正常调用所有在NEI平台上面定义的接口了。

接口测试：主要是给接口开发人员使用，提升接口交付质量，降低后期前后端的联调成本；

代码生成：目前已经支持iOS以及安卓，安卓目前已支持IDE插件，这两种代码的生成都依赖可以自定义的工程规范。

iOS 规范

工程规范结合NEI接口通过构建工具来形成项目的初始代码，工程规范本身是一个项目脚手架，除此之外还可以编写自定义模板，也可以用一些自定义规则，可以定义静态资源根目录、模板目录、接口Mock数据目录、模板Mock数据目录、JAR包目录等。

NEI资源包含异步接口、数据模型、页面模板、规则函数、客户端、业务分组等。

NEI辅助功能

批量创建：数据模型是NEI中重要的概念之一，拿NEI项目本身来说，它有User、UserGroup、Project、ProjectGroup、Page、Parameter等等可以抽象出来的对象。这些对象和程序的编写以及数据的持久化都是息息相关的。创建数据模型的时候，可以指定字段的默认值，默认值的优先级会高于 Mock 出来的随机数据，也可以定义生成规则，根据自己的逻辑生成 Mock 数据。

比如 User 对象，它的结构一般如下所示：

{

"id": "[number]",

"name": "[string]",

"email": "[string]"

}

其中，中括号里面的值表示该字段的类型。

在建好的User对象里面加一个CRUD辅助功能，可以实现批量创建接口的功能。

接口导入：通过NEI可以导入JSON和Swagger文件，还支持 HAR 和 POSTMAN 的定义数据。

分组标签：现代系统标配功能，方便资源的管理。

版本统计：因为接口会随着系统迭代出现多个版本，在NEI上可以对版本进行管理。当接口发生变更的时候，可以通过NEI快速查找正在使用该接口的客户端，保证产品功能的正常使用。

除了以上功能外，NEI还有全局搜索、接口状态、创建审核、变更管控等其他辅助功能。工程规范加上NEI资源通过构建工具形成项目的初始代码。

NEI 推荐的开发流程

在拿到交互稿后开发人员就可以介入，通过交互稿进行相应的接口设计，利用构建工具生成一个本地的模拟开发容器，前端可以在模拟容器中进行开发，接口可以mock出来，真实的接口交给后端去开发，后端开发完接口后在NEI平台上可以进行自测，最后前后端进行联调。如果大家都严格遵循在NEI上定义的接口规范，后期的联调在理论上是零成本的。

安卓绿色联盟后续会根据每期技术沙龙议题输出精彩技术干货文章，为未能现场参加技术沙龙的您提供另一个干货学习机会。