API接口文档范文-API接口文档示例

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

下方是接口文档的示例：

**API说明**

## 修订历史

## 目录

[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