api接口文档

api接口文档

1、接口概述

接口概述主要说明本接口文档涉及到的业务功能点，面向的阅读对象以及接口文档主要包括哪些业务的接口，可以让读者有一个直观的认识。如：本文档定义了中台系统面向外部接入方的数据协议接口，主要包括：用户注册接口、同步用户、授权认证等接口。适合阅读的对象为接入中台开发者或者外部合作方…。这样的一段描述，对于阅读者来说可以对整个接口文档有一个大概的认识。

2、权限说明

有的接口调用需要授权认证，在这部分需要进行说明。如果接口只是基于分配的token认证，那文档需要说明token的获取方式。如果接口需要进行签名认证，需要在这里说明签名的具体方法。

3、编码方式

接口的请求过程中可能由于编码导致乱码，所以，接口必须约定编码方式

4、请求说明

接口文档的请求说明中主要说明接口请求的域名以及请求的数据格式

5、接口列表

接口列表是接口文档的主要内容，这部分内容需要列出所有的接口名称、接口地址、接口的请求方式、接口的请求参数以及响应格式。在

接口的请求参数中我们需要说明每个参数的含义、类型以及是否必须等属性。对于接口响应结果，如果有业务字段，也需要进行说明。

6、状态码说明

接口的响应体一般都会带有响应的状态码，例如成功、失败等。状态码有助于接入方进行接口调用状态的判断。