api数据接口文档_接口文档示例（Taobao/jd/pinduoduo/开放接口调用）

api数据接口文档_接口文档示例

 本文主要是提供了一个接口文档的范文，内容修订历史、目录、时序图、接口要素描述、接口说明、使用示例、字典、FAQ。
 使用MD格式文档（makedown），选择原因，容易格式转换，开发便于修改，版本维护界面，修改记录明显，普通文本工具即可编辑。

下方是接口文档的示例：

参数说明

• 通用参数说明
  • 参数不要乱传，否则不管成功失败都会扣费
  • url说明 https://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**](#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