一：为什么要编写API接口文档
API接口文档，是开发途中，让其他协作者共同调试的重要工具，就像操作手册，给你一个物品，你可能不知道怎么使用，但是如果有操作手册，就可以让一个刚拿到物品的人，快速的进行使用物品。同理可得，API接口文档，就是为了方便其他写作者，快速理解、迅速使用，并进行接口调用操作的手册。
接口文档，大家可能在工作途中听到很多笑话，比如：程序猿最恨别人不写接口文档；程序员最不喜欢写接口文档...
其实在矛盾的同时，也体现了接口文档的重要性。
有幸，本人由于经常对接三方系统，收到了很多接口文档，其中的_形式，千奇百怪，各有千秋，有些很标准，有些就难以入目。_
二：常见的文档形式
1. webServer文档形式
- webServer文档一般用于商场或财务系统，一般这类文档包括业务实现逻辑图、Web服务分布描述（它定义了Web服务的接口，如服务名、提供的方法、方法的参数信息）；
- 请求格式一般为POST；
- 数据格式一般为XML；
2.Swagger-UI风格文档
此类文档，可以实现线上接口编辑，自动生成token实现后续接口测试调用，一般都基于RESTFUL接口规范。
此类接口可以直观的看到接口是否可用。
3.SDK文档
如题所示，对方将接口操作封装为了特定的SDK包，那么调用方只需要实例化SDK，然后就可以参照文档进行方法调用了。这种方法更为简单，对接成本低，但是要求提供者提供对应语言的SDK。这是具有一定的开发压力的。
4.线上api文档
此类api可参考威富通、高德地图、美团api、抖音api等等线上文档。此类文档基本格式相同，均具有通用性，提供的一般为http/https请求，以供各种开发语言调用。
5.API接口word文档
这类接口一般用于私有化开发提供api文档，以下也会注重讲解一下。
各个公司提供的文档规范不同，有些符合RESTFUL风格，有些则直接统一输出POST格式接口。
三：API接口word文档应该有什么
对于不规范的接口文档真的是让人头疼万分，比如，本人曾经收到一份api文档，一个sign加密算法，文档至写了四步，但是，我按照步骤进行加密时，发现无法拿到正确的值，多次确认无果之后，我协调了对方的相关开发人员，进行协助，然而，恐怖的事情出现了，我们一起调试之后，加密步骤高达14步。
不用说文档中有没有实例，就算有，神仙来了也无法调通的。
1.变更记录
变更记录是个好东西，什么时候，谁修改了什么内容，首先便于其他协作者明白这个版本更新了那些接口。需要做哪些配套调整，当然，出问题的时候，溯源的作用也是很重要的。
2.文档用途
这个文档时用于做什么，一般介绍私有化部署开发商和使用者之间的合作内容。
3.接口规范
这个板块一般介绍开放规定的接口规范，比如：传输方式（http/https）、提交方式（接口规范，restful风格或者全部为post）、数据格式、字符编码、签名算法、测试环境地址；
4.系统参数/公共参数
系统参数是每个接口都要携带的参数，描述每个接口的基本信息，用于统计或其他用途，一般放在header或url参数中；
| 参数 | 说明 |
|---|---|
| version | 版本号（版本控制） |
| time | 时间戳（防重放） |
| from | 来源（从哪里访问的接口，h5/小程序） |
| sign | 签名 |
5.签名算法
这是非常重要的一步，一个好的签名算法文档，步骤必须清晰，且每一步均有实例展示，最终获取到的sign，可以验证。
6.规范的业务编码
一般按照restful风格，返回值包括code、message、data;code为200时接口正确，其余code值均为错误；
一般需要将错误的返回值编码进行表格展示；
7.具体接口必须参数
7.1 接口名称
这个不用解释吧，一个正确的接口名称，是非常重要的
7.2接口介绍
这个接口使用做实现什么功能。
7.3接口请求格式
基于RESTFUL风格，需要在每个接口注明接口的请求格式，POST、GET、PUT、DELETE;
7.4接口地址
就是接口的api地址
7.5接口入参
入参解释，包括字段名称、是否必填、字段属性、字段说明；
7.6接口出参/返回值
出参解释，包括字段名称、是否必填、字段属性、字段说明；
7.7 请求示例
一般建议将域名或者测试地址一起拼写展示
7.8 入参示例
如下
7.9 出参示例
如下
四：API接口文档示例
五：结束
本文主要是结合了我最近和三方合作的经验，为大家整理了一份让其他人可以清楚的看明白的接口文档说明，希望能够帮助到大家。大家如果有比较好的文档编写规范，也可以给我提出来，大家共同进步。
寄语
世界因规则而美丽
