技术·文档 | 标准API文档规范 1.0

时间 2020-02-23

标签技术文档标准 api 规范 1.0 繁體版

原文原文链接

背景

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

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

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

那么痛点在哪里？编程

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

撸码一分钟,对接三小时bash

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

API文档概述

什么是API

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

什么是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	交易拒绝	此交易被系统拒绝