背景

随着业务的发展，支撑平台的项目也是越来越多。

同时，为了让业务系统更加清晰，会从整个平台项目的架构体系，对系统业务水平拆分、垂直分层，产生了一系列平台和子系统，并使用接口进行数据交互。

伴随着业务的发展，接口文档会越来越多。

那么痛点在哪里？

代码和文档不匹配，代码接口更新，文档不更新，且接口文档内容和形式百花齐放，不便于理解。

撸码一分钟,对接三小时

为了解决这些痛点，我们定义了如下接口文档规范，用于编写API接口时的指导，以便于你写出良好规范的API文档。

API文档概述

什么是API

API（Application Programming Interface）即应用程序编程接口，是一些预先定义的函数，是连接客户端与服务端的桥梁，可以为应用程序与开发人员提供基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

什么是API文档

API文档是面向API使用者对API功能、用法和版本等信息等详尽描述，API文档增加了API等易用性，是API开发者面向使用者对公开约束。

什么是好的API文档

好的API接口文档对于使用者来说必须满足以下几个点：

• 易学习：

有完善的文档及提供尽可能多的示例，文档要遵循行业和国际标准，让有经验和背景的调用者可以快速上手。

例如，定义国家代码，要使用ISO-3316国家代码标准中的国家代码，中国是“CN”，而不是自己造一个“CHI”，以免造成误解。

• 易使用：

对于读者来说，文档没有复杂的程序和业务细节，只要易于读者学习即可。

灵活的API允许按字段排序、可自定义分页、排序和筛选等。一个完整的API意味着被期望的功能都包含在内。

• 难误用：

详细的错误提示，用户可从文档的阅读中了解API的使用方法和误区，不会在调用API的时候出现“惊喜”。

• 兼容性

API的升级要考虑向下兼容，文档也要考虑前后一致。

例如尽量避免在版本1是必填的参数，在版本2改为非必填，等等。

• 实时性

文档也相应地要考虑随着版本的更新而更新，且与服务一致。

避免客户端根据老的文档而请求新的接口而造成与预期不一致。

API文档目录

下面定义了标准的接口文档目录格式：

1.修订历史
2.接口描述
3.服务接入
    基本信息
    服务信息
4.请求和返回参数
    请求参数
    返回参数
5.成功和异常示例
    成功示例
        请求参数
        返回参数
    异常示例
        请求参数
        返回参数
6.状态码
    错误码
    业务码

API文档示例

下面提供了标准的接口文档的简要示例，可以在创建API文档的时候参考此结构和示例。

修订历史

以下为本文档对修订历史，倒序排列。

原则上，无论API发生了任何定义、约束和功能上的变更，都应该体现在以下修订历史中，同时强烈建议在接口发生变更以后升级版本，并尽可能保证向下兼容（即如果客户端没有更新API也可以正常使用之前的功能）。

日期	版本	说明	修订人
2019-12-12	1.0.3	这里是修订说明	刘备
2019-12-12	1.0.2	这里是修订说明	张飞
2019-12-12	1.0.1	这里是修订说明	刘备

接口描述

以下为文档的概要描述，简要说明了此接口提供的能力、覆盖的业务场景、相关的系统角色等。

服务接入

此处描述了接口的形式（RPC、HTTP等）、接口的地址、客户端等配置等信息。

基本信息

接口地址	com.example.api/transfer/v1/
请求方式	HTTP / POST
是否需要授权	是
调用频率限制	900次/秒

服务信息

如果是请求RPC接口，需要增加如下描述。

• 服务AppId：AppPAyService

• 接口：com.example.pay.TransferService

• 方法：transfer

• maven依赖

开发联调时使用SAPSHOT版本,上UAT前需要更换最新RELEASE版本

<dependency>
  <groupId>com.example.pay</groupId>
  <artifactId>pay-transfer</artifactId>
  <version>最新RELEASE版本</version>
</dependency>

• 接口定义

public interface TransferService {
    Response<Result> transfer(Request request);
}

数据模型

一个完整的数据模型定义应包括：

路径与查询字符串参数模型
请求体参数模型
响应体参数模型

下面列举了请求和返回参数的数据模型定义示例，其中“变量名|类型|是否必填”是组成一个参数的最小数据集（MDS），即一个完成的参数定义至少要有这三个信息。

请求参数

字段名	变量名	类型	是否必填	最大长度	描述	示例值
商户号	mchId	String	是	32	系统分配的商户账户	100098
金额	amount	Int	是		转账金额，单位：分	200

返回参数

字段名	变量名	类型	是否必填	最大长度	描述	示例值
流水号	txnId	String	否	32	交易流水号	2019022018061908
状态码	status	Int	是	1	是否成功,0:成功,1:失败	1
错误码	errorCode	Int	否	4	系统分配的商户账户	401
错误描述	desc	String	否	128	备注说明	操作成功

对接示例

成功示例

请求参数

{
    "mchId":"1000008",
    "amount":900
}

返回参数

{
    "txnId":"2019022018061909",
    "status":0
}

异常示例

请求参数

{
    "mchId":"100000",
    "amount":100
}

返回参数

{
    "status":1
    "errorCode":404,
    "desc":"商户不存在"
}

状态码

错误码

错误代码	描述	原因	解决方案
401	没有授权	客户端IP没有授权	在服务端进行授权
404	商户不存在	非系统商户	检查是否是分配的商户号

业务码

业务码	描述	说明
ACCEPT	交易接受	交易被系统接受
REJECT	交易拒绝	此交易被系统拒绝