一：为什么要编写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参数中；

参数	说明
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接口文档示例

五：结束

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

寄语

世界因规则而美丽

如何写一个合格的API文档相关推荐

分享一个自行开发的加强版swagger-ui，提供一个全新的api文档生成思路
我前段时间开发的加强版swagger-ui. 这或许为swagger应该是一个什么样子, 提供了一个全新的思路. 文档缓存,即使服务器没开,仍然可以看文档. 文档注释增强,采用js注释写法,对前端人员 ...
itextpdf api帮助文档_我开源了一个小工具，可以帮你轻松生成 SpringBoot API 文档...
前言大家好,我叫叶大侠,一名独立开发者.这个文档工具是我17年的一个想法,当时还是在公司里面上班,负责App客户端的开发工作,当时后端童鞋写文档的意愿比较低,总是要等他们开发完接口,然后才在微信上沟 ...
【资源推荐】良心之作！超过 10000+ 的互联网团队正在使用的在线 API 文档、技术文档工具...
搞开发的同学都知道一个好的 API 文档是有多重要! 每当接手一个别人开发好的项目,看着那些没有注释的代码,真的头大. 程序员都很希望别人能写技术文档,因为可以提高自己开发的效率,而往往自己却很不希望 ...
JSDoc --JS API文档生成器
JSDoc 是一个JavaScript的API文档生成器. 他可以让开发者在开发的过程中, 将编写的注释通过JSDoc工具生成一个api文档, 妈妈再也不用担心我不会写接口文档了. 这里是原作者Git ...
良心之作！超过 10000+ 的互联网团队正在使用的在线 API 文档、技术文档工具
搞开发的同学都知道一个好的 API 文档是有多重要! 每当接手一个别人开发好的项目,看着那些没有注释的代码,真的头大. 程序员都很希望别人能写技术文档,因为可以提高自己开发的效率,而往往自己却很不希望 ...
jstree中文api文档_还在用 Swagger（丝袜哥）生成接口文档？我推荐你试试它。。。...
作者:小鱼儿511https://blog.csdn.net/dongbeiou/article/details/106771453JApiDocs是一个无需额外注解.开箱即用的SpringBoot接 ...
springboot的api_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
android api文档_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
Eolink 征文活动- -后端研发需要的API文档工具
Eolink功能太多,一两篇文章聊不完,这篇文章只是聊聊Eolink的API文档管理功能. 首先大致说说我所认知的API文档工具历史. 我所知的API文档工具历史我是2010年左右参 ...

如何写一个合格的API文档