接口文档规范简要说明

接口文档又叫（规范性文档）。接口文档有规范的格式和内容要求，后端按照接口协议接收前端传递的合法数据和返回符合的规范的数据，前端按照接口协议传递符合规范的数据和对后端返回的数据依据展示的需要做处理。

首先接口分为六部分：接口描述、接口地址、请求类型、请求方式、请求体参数说明、返回成功参数说明

一、接口描述

简单描述该接口的功能，例如：根据哪些条件查询、新增、修改、删除什么信息。

二、接口地址

接口地址需要遵从URL的命名规范来编写

1、格式规范：http://域名:【端口】/应用组名称/版本/访问控制/【应用组件】/域对象/【动作】

2、命名时使用后英文小写字母、域对象使用名词复数形式，不可以使用动词、域对象关系表达最大不超过2层

3、统一动词

添加/增加：add

提交：submit

更新/修改/编辑：update

删除：delete

详情：info

条件查询（不分页）：query

条件查询（分页）：pagelist

条件查询（树形）：tree

导入：import

导出：export

生成：generate

指派/分配：assign

暂存/草稿：savedraft

变更：change

评议：discuss

启动：start

停止：stop

三、请求类型

application/json

四、请求方式

新增(post)、 修改(put) 、删除(delete) 、获取(get)

五、请求体参数说明

共有五列：参数名、参数说明、参数类型、是否必填、示例值

1、参数名：类的属性，字段名

2、参数说明：中文解释

3、参数类型：属性类型，有Long、String、Int、Object、List、File等类型；

4、是否必填：请求时参数名是否必填

5、示例值：写上请求体参数例子，以便前端更好理解

六、返回成功参数说明：

返回参数结构有几种情况：

1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；

2、如果要返回某些参数，则有两个结构体：code/mesage/data，data里写返回的参数,data是object类型；

3、如果要返回列表，那么有三个结构体，code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

七、其他

我觉得一份好的接口文档应该包括以下内容：

1、接口概述：包括接口的名称、描述、版本号等信息，让开发者了解接口的基本信息。

2、接口参数：包括请求参数和返回参数，需要详细说明每个参数的名称、类型、描述、默认值、是否必须等信息，让开发者清晰地知道每个参数的含义和使用方法。

3、接口使用示例：提供一个或多个请求和相应的示例，让开发者更好地理解接口的使用方法和返回结果。

4、接口错误码：列出所有可能出现的错误码和相应的错误信息，让开发者了解如何识别和处理接口返回的错误。

5、接口限制和安全性：包括接口的访问限制、频次限制、安全性等信息，让开发者知道如何正确地使用接口。