api数据接口文档_接口文档示例（淘宝/拼多多API接口文档）
api数据接口文档_接口文档示例
本文主要是提供了一个接口文档的范文，内容修订历史、目录、时序图、接口要素描述、接口说明、使用示例、字典、FAQ。 使用MD格式文档（makedown），选择原因，容易格式转换，开发便于修改，版本维护界面，修改记录明显，普通文本工具即可编辑。
下方是接口文档的示例：
taobao API 接入说明
-
API地址:
申请调用KEY地址 -
调用示例：
<?php
// 请求示例 url 默认请求参数已经URL编码处理
// 本示例代码未加密secret参数明文传输，若要加密请参考
$method = "GET";
$url = "https://api-gw…….cn/taobao/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=652874751412&is_promotion=1";
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,FALSE);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,FALSE);
curl_setopt($curl, CURLOPT_FAILONERROR, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);
curl_setopt($curl, CURLOPT_ENCODING, "gzip");
var_dump(curl_exec($curl));
?>
-
参数说明
-
通用参数说明
- 参数不要乱传，否则不管成功失败都会扣费
- url说明 api-gw.onebound.cn/平台/API类型/ 平台：淘宝，京东等， API类型:[item_search,item_get,item_search_shop等]
- version:API版本
- key:调用key,测试key:test_api_key
- secret:调用secret,测试secret:(不用填写)
- cache:[yes,no]默认yes，将调用缓存的数据，速度比较快
- result_type:[json,xml,serialize,var_export]返回数据格式，默认为json
- lang:[cn,en,ru] 翻译语言，默认cn简体中文
- secret:密钥
-
API:item_search 参数说明：
- q:搜索关键字
- cat:分类ID
- start_price:开始价格
- end_price:结束价格
- sort:排序[bid,bid,bid2,_bid2,_sale,_credit]
(bid:总价,bid2:商品价格,sale:销量,credit信用,加前缀为从大到小排序) - page:页数
- page_size:每页宝贝数量，默认40
- seller_info:是否获取商家信息[yes,no],默认yes
-
API:item_get 参数说明: num_iid:宝贝ID
-
API说明
修订历史
| 日期 | 内容 | 版本 | 作者 | | ———- | ———————————————————— | ——– | —— | | 2021/09/10 | 初稿 | Ver. 1.0 | NHK|
目录
[TOC]
文档介绍 本文档用于XXX业务的接口说明和使用说明。
功能时序图
“sequence API-> APISERVER: 系统连接 APISERVER -> API: 连接成功 API -> APISERVER: 系统登录 APISERVER –> API: 登录成功 API -> APISERVER: 业务请求 APISERVER –> API: 业务响应 API -> APISERVER: …… APISERVER –> API: …… API –> APISERVER: 系统连接断开 APISERVER -> API: 系统连接断开响应 “
接口要素描述
术语定义
– **JAVAGW：**系统的网关，有路由、广播等功能。 – **JAVAAPI：**JAVA语言所调用的程序，提供JAVA语言的API接口。直接连接JAVAGW。 – **APISERVER：**对外提供JSON格式接口，连接JAVAGW。 – **C++API ：**为C++语言提供的程序，连接APISERVER。 – **PythonAPI：**为PythonAPI语言提供的程序，连接APISERVER。 – **C#API ：**为C#语言提供的程序，连接APISERVER。
语法描述
基础语法
接口使用JSON格式传输，语法规则遵循JSON语法规则。
描述语法 – **【0..0】：**表示无需赋值。 – **【0..1】：**表示可以有0个或1个实例。 – **【1..1】：**表示只能有一个实例。 – **【1..】：**表示至少有一个实例。 – **【0..】：**表示对实例的数目没有限制。 – **【X.Y】：**表示X集合内的Y属性。示例：参数【orderList.exchId】，orderlist中exhcId的参数，订单集合中市场属性。 – **【X^】：**表示X的集合中，有一个参数必送。示例：参数A ，参数标识【X^】 参数B ，参数标识【X^】 ，参数A、B必送一个。
数据类型
int：整数类型
long：长整型
double:浮点类型
String：字符串
list:代表数组或集合
接口清单
功能列表
| 接口 | 名称 | 接口支持 | | —– | —————— | ——– | | 100000 | 功能1 |[✔]JAVA[✔]python|
100000 -功能1
接口定义
注意事项
参数说明
请求参数
| 参数 | 中文名称 | 类型 | 长度 | 参数标识 | 示例值 | | ———————————————- | ———————————————- | ——– | —– | ——– | —— | | value | 值1 | String | 1 | 【1..1】 | | | ValueList | 值对象列表 | list | 999 | 【0..】 | | | 【ValueList.value1】 | 值对象1 | String | 35 | 【0..】 | | | ValueList1 | 值列表1 | list | 999 | 【0..*】 | |
响应参数
| 参数 | 中文名称 | 类型 | 长度 | 参数标识 | 示例值 | | —————————————— | ———— | ——– | —- | ——– | —— | | successFlg | 成功失败标志 | int | 1 | 【1..1】 | 0 | | errorCode | 错误代码 | String | 8 | 【0..1】 | | | failInfo | 错误信息 | String | 200 | 【0..1】 | | | value | 存取值1号 | string | 24 | 【1..*】 | |
DEMO范例
JAVAAPI
com.xxx..api.Interface.func(Funcvalue value)
“java ….. “
使用示例（业务场景）
XXX业务使用用例说明
变更说明
XXX示例
数据字典
successFlg-成功失败标识
|字典代码|名称|描述| |——|————–|——–| |0|成功|| |1|失败||
FAQ
上一篇
