如何写一个合格的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接口文档示例五:结束版权声明: 本站仅提供信息存储空间服务,旨在传递更多信息,不拥有所有权,不承担相关法律责任,不代表本网赞同其观点和对其真实性负责。如因作品内容、版权和其它问题需要同本网联系的,请发送邮件至 举报,一经查实,本站将立刻删除。