参考
https://www.kancloud.cn/liupeizhi/openapi/292276
https://blog.csdn.net/qq_41961113/article/details/80347341
https://www.cnblogs.com/xiezhi/p/6434812.html

正确规范写接口文档
前言
　　正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。

接口规范内容
接口名称
场景说明
接口说明
请求参数
响应参数
错误码
参数内容

字段名
变量名
是否必填
类型
示例值
描述

错误码内容

名称
描述
原因
解决方案

一.银联接口文档示例 （适用于接口规范文件）
5.2.2 统一收单线下交易查询
5.2.2.1 场景说明
收单机构可以通过该接口主动查询订单状态，完成下一步的业务逻辑。需要调用查询接口的情况:

当收单机构后台、网络、服务器等出现异常，收单机构系统最终未接收到支付通知;调用支付接口后，返回系统错误或未知交易状态情况;调用alipay.trade.pay，返回INPROCESS的状态;调用alipay.trade.cancel之前，需确认支付状态。

5.2.2.2 接口说明
公共请求参数中的method填写alipay.trade.query。

5.2.2.2.1 请求参数
参数 参数名 类型 是否必填 最大长度 描述 示例值
out_trade_no 商户订单号 String 否 32 订单支付时传入的商户订单号,和网联交易号不能同时为空。trade_no,out_trade_no如果同时存在优先取trade_no 20150320010101001
... ... ... ... ... ... ...
trade_no 网联交易号 String 否 64 网联交易号，和商户订单号不能同时为空 2014112611001004680073956707
5.2.2.2.2 响应参数
参数 参数名 类型 是否必填 最大长度 描述 示例值
trade_no 网联交易号 String 是 64 网联交易号 2013112011001000000121536
... ... ... ... ... ... ...
out_trade_no 商户订单号 String 是 32 商户订单号 6823789339978240
TradeFundBill字段说明:
参数 参数名 类型 是否必填 最大长度 描述 示例值
fund_channel 资金渠道 String 是 32 交易使用的资金渠道 ALIPAYACCOUNT
... ... ... ... ... ... ...
5.2.2.3 错误码
错误码 错误描述 原因 解决方案
SYSTEMERROR 接口返回错误 系统超时 请不要更换商户退款单号，请使用相同 参数再次调用 API。
NOTENOUGH 余额不足 商户可用退 款余额不足 此状态代表退款申请失败，商户可根据 具体的错误 示做相应的处理。
... ... ... ...
二.API开发接口文档示例 （适用于http、https 接口）
3.1.1 查询排重接口
3.1.1.1 场景说明
查询信息是否已存在。

3.1.1.2 接口详情
3.1.2.1 接口地址
接口详情
地址 http://www.baidu.com （正式环境）
请求方式 GET
3.1.2.2 参数
参数 是否必填 说明
idfa 是 广告标识符
... ... ...
source 是 渠道来源，具体值在接入时再进行分配
3.1.2.3 返回结果
返回结果 格式 JSON
状态码 10000 success（调用成功）
... ...
10010 access prohibited(访问拒绝)
3.1.1.3 调取示例
3.1.1.3.1 查询成功
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 1 //已经存在
}
}
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
}
}

3.1.1.3.2 接口调用失败
{
"state": 10010,
"message": "access prohibited",
"data": [
]
}

本文来自 qq_41961113 的CSDN 博客 ，全文地址请点击：https://blog.csdn.net/qq_41961113/article/details/80347341?utm_source=copy

一、什么是接口文档？
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

二、为什么要写接口文档？
1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发
2、项目维护中或者项目人员更迭，方便后期人员查看、维护

三、接口规范是什么？
首先接口分为四部分：方法、uri、请求参数、返回参数
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾；url参数就不说了。
3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填
字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。
4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

注意：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开

不懂接口的程序员就不懂开发
开发人员的面试中，面试者常常描述不清做过的项目。原因很简单，要么你不懂接口，要么你描述不清接口。描述接口有两个重点，称为2P：一是协议（Protocol），二是原型（Prototype），它们分别描述..

本文来自 爪哇_怪盗基德 的CSDN 博客 ，全文地址请点击：https://blog.csdn.net/qq_40140473/article/details/78220845?utm_source=copy

开发人员的面试中，面试官经常会让你描述之前做过的一些项目，以及你在其中开发的部分。看似很简单，很多人就是讲不清楚，要么寥寥几句讲不清楚，要么东扯西凑不着重点。原因很简单，要么你不懂接口，要么你描述不清接口。

小白面试者：“我做过手机开发，最近一个项目是个在线订餐的APP，我做的用户下单，订单列表这块功能。”
资深面试官：“好，说说你是怎样从后台取一个用户的订单列表的。”
小白：“调一个函数。。。呃，就从后台取到数据。。。然后显示到页面上。”
资深：“调什么样的函数，它是怎么与后台通讯的？后台返回的数据是什么样子？”
小白：“调ajax，后台会返回一个数组。。。”
资深心想：“呵呵，啥叫后台返回数组，接口协议的过程完全不清楚。问问看接口原型能不能讲清楚。”，问：“数组的具体数据结构你能描述一下吗？”
小白：“就是一个变量。。。没有结构啊。。。”
资深（心想）：“捉急啊，数据类型也讲不清楚，真奇怪应用是怎么做出来的。。。”

一个表达良好且真实做过这块开发的程序员，应该有能力描述出细节：前端通过HTTP协议发出请求，调用这样的语句$.get("api/queryOrder?status=1")，可以用参数status表示只取指定状态的订单，后端返回JSON格式的数据，它表示是一个数组，数组每一项是个订单（Order类型），订单的属性有整型的id, 数值型的总价total等。

重点抓到了吗？首先他是大体知道通讯协议（HTTP/JSON等），并且可以详细描述出怎样调用后台；其次，对这次调用，他可以清楚的描述出了参数和返回值的类型、含义这些细节，对原型有一定描述能力。

而他可能对HTTP协议的细节不太了解。如果是个爱钻研或资深些的开发，可以把HTTP协议交互的细节讲清楚：
前端以HTTP GET方式向后端发出请求，发送请求像这样：

GET api/queryOrder?status=1
1
其中，应用层定义网址中，queryOrder是调用名，status是调用函数，参数通过urlencoded方式传递。后端成功时返回数据像这样：

200 OK

[{id:1, dscr:"order 1", total:100}, {id:2, dscr:"order 2", status:1}]
1
2
3
能说到这个程度，接口协议这一块已经很懂了。如果再遇到抽象能力强的，会直接写出形式化的接口原型，像这样：

queryOrder(status) -> [ {id, dscr, total} ]
1
那么这已经是精通前后端通讯的架构师水平了。

看到这里，新手会若有所思，但还是不禁要问，“到底啥叫接口？是Java里面那个Interface关键字吗？”没错，接口的英文是Interface。不过它不局限于是一个关键字，而是一组设计思想：

把待开发对象的接口理清楚，就决定了你对需求的理解程度和设计方案的方向正确性，其实就是需求分析和概要设计，它也同时决定了测试设计的质量。
把对象的内部接口理清楚（划分模块，理清它们之间的交互），决定了方案的实现，其实就是详细设计和编码的工作。
代码写乱了，已经难以理解了，这时要使用接口分离，这叫重构。
怎样才能把接口描述清楚呢？描述接口有两个重点，称为2P：一是协议（Protocol），二是原型（Prototype），它们分别描述了交互的方式与内容。协议说的是，调用方和被调用方是怎样交互的，比如基于HTTP协议，请求参数用urlencoded格式，返回内容用JSON格式；原型描述的是一个请求的内容，调用名称，参数和返回内容是什么含义，以及类型。

大到软件工程，小到编写个去后台获取订单列表的函数，多半的时间都花在确定接口和实现接口上。

下一节，我再和大家聊聊各种接口以及每种接口的表示。

本文来自 天笑2001 的CSDN 博客 ，全文地址请点击：https://blog.csdn.net/skyshore/article/details/50995163?utm_source=copy

我们此次后端api的实现主要是按照RESTful api规范来设计的，就是符合REST架构下设计api的规范。简单的来说REST结构就是：利用URL定位资源，用HTTP动词(GET,POST,PUT,DELETE)来描述相应操作。

   RESTful api主要的意义在于它可以让在不同形式的前端所接受到的用户请求能够统一的发送到一个后台并返回不同的前端。RESTful api是由后端SERVER实现并提供给前端来调用的一个接口。前端调用API来向后台发起HTTP请求，后台响应请求并将处理结构反馈给前端。所以说RESTful是典型的基于HTTP的协议。所以下面我们对RESTful api的设计原则与规范进行相应的说明：

一、协议
API与用户的通信协议，总是使用HTTPs协议。

二、域名
尽量将API部署在专用域名之下：

例如https://api.jupiter.com

三、版本
将我们API的版本号放入URL中：

例如https://api.jupiter.com/v1/

四、路径
路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样：

      https://api.jupiter.com/zoo

      https://api.jupiter.com/animals

      https://api.jupiter.com/employees

五、HTTP动词
对于资源的具体操作类型，由HTTP动词来表示，常用的HTTP动词有下面五个(括号中对应的是相应的SQL命令)：

    GET（SELECT）：从服务器取出资源（一项或多项）。

    POST（CREATE）：在服务器新建一个资源。

    PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

    PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

    DELETE（DELETE）：从服务器删除资源。

    下面是一些简单的例子：

    GET /zoos：列出所有动物园

    POST /zoos：新建一个动物园

    GET /zoos/ID：获取某个指定动物园的信息

    PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）

    PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）

    DELETE /zoos/ID：删除某个动物园

    GET /zoos/ID/animals：列出某个指定动物园的所有动物

    DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

六、过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果，下面是一些常见的参数：

    ?limit=10：指定返回记录的数量

    ?offset=10：指定返回记录的开始位置。

    ?page=2&per_page=100：指定第几页，以及每页的记录数。

    ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

    ?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

七、状态码
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）：

    200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

    201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。

    202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）

    204 NO CONTENT - [DELETE]：用户删除数据成功。

    400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

    401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。

    403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。

    404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

    406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

    410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。

    422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

    500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

详细的状态码列表可见这里。

八、错误处理
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

    例如：

{
error: "Invalid API key"
}
九、返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：

  GET /collection：返回资源对象的列表（数组）

  GET /collection/resource：返回单个资源对象

  POST /collection：返回新生成的资源对象

  PUT /collection/resource：返回完整的资源对象

  PATCH /collection/resource：返回完整的资源对象

  DELETE /collection/resource：返回一个空文档

本文来自 qq_31805915 的CSDN 博客 ，全文地址请点击：https://blog.csdn.net/qq_31805915/article/details/79951929?utm_source=copy

整体规范建议采用RESTful 方式来实施。

协议

API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。

域名

应该尽量将API部署在专用域名之下。
https://api.example.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https://example.org/api/

api版本控制

应该将API的版本号放入URL。
https://api.example.com/v{n}/
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

采用多版本并存，增量发布的方式
v{n} n代表版本号,分为整形和浮点型
整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2
浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

API 路径规则

路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

HTTP请求方式

对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面四个（括号里是对应的SQL命令）。
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）：从服务器删除资源。

下面是一些例子。

GET /product：列出所有商品
POST /product：新建一个商品
GET /product/ID：获取某个指定商品的信息
PUT /product/ID：更新某个指定商品的信息
DELETE /product/ID：删除某个商品
GET /product/ID/purchase ：列出某个指定商品的所有投资者
get /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?producy_type=1：指定筛选条件

API 传入参数

参入参数分为4种类型：

地址栏参数

• restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息
• get方式的查询字串 见过滤信息小节
  请求body数据
  cookie
  request header

cookie和header 一般都是用于OAuth认证的2种途径

返回数据

只要api接口成功接到请求，就不能返回200以外的HTTP状态。
为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。

接口返回模板：

{
status:0,
data:{}||[],
msg:’’
}

status: 接口的执行的状态

=0表示成功
<0 表示有异常=""

Data 接口的主数据

，可以根据实际返回数组或JSON对象

Msg

当status!=0 都应该有错误信息

非Restful Api的需求

由于实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的，因此，需要有一些api突破restful规范原则。特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。

页面级的api

把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据

举例

api/v1/get-home-data 返回首页用到的所有数据

这类API有一个非常不好的地址，只要业务需求变动，这个api就需要跟着变更。

自定义组合api

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级api，具备更高的灵活性，同时又能很容易的实现页面级的api功能。

规范

地址：api/v1/batApi

传入参数：

data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]

返回数据

{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}

Api共建平台

RAP是一个GUI的WEB接口管理工具。在RAP中，您可定义接口的URL、请求&响应细节格式等等。通过分析这些数据，RAP提供MOCK服务、测试服务等自动化工具。RAP同时提供大量企业级功能，帮助企业和团队高效的工作。

什么是RAP?

在前后端分离的开发模式下，我们通常需要定义一份接口文档来规范接口的具体信息。如一个请求的地址、有几个参数、参数名称及类型含义等等。RAP 首先方便团队录入、查看和管理这些接口文档，并通过分析结构化的文档数据，重复利用并生成自测数据、提供自测控制台等等... 大幅度提升开发效率。

RAP的特色

强大的GUI工具 给力的用户体验，你将会爱上使用RAP来管理您的API文档。
完善的MOCK服务 文档定义好的瞬间，所有接口已经准备就绪。有了MockJS，无论您的业务模型有多复杂，它都能很好的满足。
庞大的用户群 RAP在阿里巴巴有200多个大型项目在使用，也有许多著名的公司、开源人士在使用。RAP跟随这些业务的成行而成长，专注细节，把握质量，经得住考验。
免费 + 专业的技术支持 RAP是免费的，而且你的技术咨询都将在24小时内得到答复。大多数情况，在1小时内会得到答复。
RAP是一个可视化接口管理工具 通过分析接口结构，动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。我们的口号：提高效率，回家吃晚饭！