如何写一个合格的API文档

一：为什么要编写API接口文档

API接口文档，是开发途中，让其他协作者共同调试的重要工具，就像操作手册，给你一个物品，你可能不知道怎么使用，但是如果有操作手册，就可以让一个刚拿到物品的人，快速的进行使用物品。同理可得，API接口文档，就是为了方便其他写作者，快速理解、迅速使用，并进行接口调用操作的手册。

接口文档，大家可能在工作途中听到很多笑话，比如：程序猿最恨别人不写接口文档；程序员最不喜欢写接口文档…

其实在矛盾的同时，也体现了接口文档的重要性。

有幸，本人由于经常对接三方系统，收到了很多接口文档，其中的_形式，千奇百怪，各有千秋，有些很标准，有些就难以入目。_

二：常见的文档形式

常见文档有以下几种形式

1. webServer文档形式

• webServer文档一般用于商场或财务系统，一般这类文档包括业务实现逻辑图、Web服务分布描述（它定义了Web服务的接口，如服务名、提供的方法、方法的参数信息）；
• 请求格式一般为POST；
• 数据格式一般为XML；

2.Swagger-UI风格文档

此类文档，可以实现线上接口编辑，自动生成token实现后续接口测试调用，一般都基于RESTFUL接口规范。
此类接口可以直观的看到接口是否可用。
地址：https://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参数中；

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接口文档示例

五：结束

本文主要是结合了我最近和三方合作的经验，为大家整理了一份让其他人可以清楚的看明白的接口文档说明，希望能够帮助到大家。大家如果有比较好的文档编写规范，也可以给我提出来，大家共同进步。

寄语

世界因规则而美丽