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

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

下方是接口文档的示例:

**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

你可能感兴趣的:(开发语言,api,接口)