接口文档怎么写,包含哪些内容

建站产品知识 2021-12-15 22:54:18

接口文档是什么

接口文档是我们做项目开发中必备的一个文档,在项目开发中,web项目的前端、后端要分离开发,结合APP开发,需要由前后端工程师共同定义接口,并将这些接口编写成接口文档,之后团队的成员按照这个接口文档进行项目的开发,在这个项目结束之前这些接口都需要一直进行维护。

接口文档

写接口文档的目的

写接口文档和写需求文档是一样的都是为了项目的开发过程中有一个统一的文件,团队成员好进行沟通、交流、协调工作。

同时有了接口文档,我们后期在逻辑或迭代方面能够方便查错和维护。

接口文档包含的内容

接口文档主要包含六个方面,下面我们一一来进行说明。

1.接口名字

对每个接口进行命名,方便查看和分类。

2. 描述(描述清楚接口的功能)

接口的描述也就是对接口的功能进行详细的阐述,说明接口设计到的业务功能点,如:文档定义了系统面向外部接入方的数据协议接口。  

主要包括:用户注册接口、同步用户、授权认证、数据接入等。

接口描述面向的阅读对象要注意,为接入中台开发(指企业管理和运营的一体化管理平台)者或是其他合作方。让他们对这些接口有一个整体的认知。

权限的说明,有些接口是需要调用授权认证的,这部分接口要进行说明,如果是token认证,那文档要说明token的获取方式,如果是其他认证方式也要说明具体的方法。

3. uri(统一资源标志符)

以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾。

与urL有些区别的是,URL还定义了如何访问资源,有资源定位信息,而uri仅作为资源标识作用。

ps:uri地址中是不允许出现大写字母的,统一用小写字母表示。

4. 请求参数

字段是类的属性;说明是中文释义;类型是属性类型,只有String、Number、Object、Array四种类型;

文档中需要将这些备注清楚,最好通过例子来进行阐述,方便阅读者读懂,好让前端能更好理解,是否必填是字段的是否必填。

5. 传入参数

我们上面已经将参数列出来了,如何我们要传输参数,按照对应的类传入相应的数据即可。

6. 返回值

关于返回值也就是我们接口接入口,调用是成功还是失败,我们需要有一个反回值进行反馈。

返回参数

包含如:反回结果、状态码、接口类型、错误参数、说明(成功多少,失败多少)等。

接口文档主要是写明白要什么数据、如何从数据库获取数据、同时如何组织好这些数据,将这些写明白,基本上就差不多了。

以上就是关于“接口文档内容写法”的相关介绍,希望对大家有所帮助。我是熊熊SEO,干货持续更新中,敬请关注,原创发布,谢绝转载抄袭。

版权声明

本文系熊熊SEO原创发表,切勿转载,否则必究

分享:

扫一扫在手机阅读、分享本文