- 正文榜首句：我正在参与掘金创作者训练营第6期， 点击了解活动详情
一：为什么要编写API接口文档
API接口文档，是开发途中，让其他协作者共同调试的重要工具，就像操作手册，给你一个物品，你可能不知道怎么运用，可是如果有操作手册，就能够让一个刚拿到物品的人，快速的进行运用物品。同理可得，API接口文档，便是为了便利其他写作者，快速了解、敏捷运用，并进行接口调用操作的手册。
接口文档，咱们可能在工作途中听到许多笑话，比方：程序猿最恨别人不写接口文档；程序员最不喜爱写接口文档…
其实在矛盾的一同，也体现了接口文档的重要性。
有幸，自己由于经常对接三方体系，收到了许多接口文档，其间的_方法，千奇百怪，各有千秋，有些很标准，有些就难以入目。_
二：常见的文档方法
常见文档有以下几种方法
1. webServer文档方法
- webServer文档一般用于商场或财政体系，一般这类文档包含事务完成逻辑图、Web服务散布描述（它界说了Web服务的接口，如服务名、供给的办法、办法的参数信息）；
- 恳求格局一般为POST；
- 数据格局一般为XML；
2.Swagger-UI风格文档
此类文档，能够完成线上接口编辑，自动生成token完成后续接口测验调用，一般都基于RESTFUL接口标准。
此类接口能够直观的看到接口是否可用。
地址：teevid.github.io/mwapi/index…
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接口文档示例
五：结束
本文主要是结合了我最近和三方合作的经验，为咱们整理了一份让其他人能够清楚的看明白的接口文档说明，期望能够协助到咱们。咱们如果有比较好的文档编写标准，也能够给我提出来，咱们共同进步。
寄语
国际因规矩而美丽
