一套程序员用的HTTP 协议模板

程序员利器之 Markdown格式，以下是具体内容。

# xxx 的 HTTP 协议说明

1. 支持的协议，必须是基于 RESTFul 架构的 HTTP 协议，数据传输的格式要求为 JSON 。
2. 请按文档说明，使用响应的 HTTP Method（ GET、POST）。
3. `rdsBaseUrl` 为：
   - `http://host:8080/api` 。
   - `https://host:8090/api` 。
4. Request 和 Response 正文均基于 JSON，UTF-8 编码。如果有问题，尝试设置 HTTP 请求 Header 的 content-type 和 accept 为 `application/json` 。
5. 请正确处理 HTTP Response Status，如 200、201、204、400、401、403、404、405、500、502。每个接口文档会有详细说明。
6. 如有歧义（尤其是需要上位系统提供数据的地方），及时交流。

【更新记录】

| 序号 |    时间    | 操作者 | 备注                   |
| :--: | :--------: | :----: | ---------------------- |
|  1  | 2023-01-01 |  xxx  | 第一版协议。           |
|  2  | 2023-01-02 |  xxx  | ① 修改了接口1的描述。 |
|      |            |        |                        |

【接口列表】

| 序号 | 接口名称 | 备注                                  |
| :--: | -------- | ------------------------------------- |
|  1  | 模板1    | 没有任何参数的接口模板                |
|  2  | 模板2    | 只有请求正文（RequestBody）的接口模板 |
|      | ……     |                                       |
|  n  | 模板n    |                                       |

## 模板1 - 无任何请求参数

### 接口描述

简要的描述这个接口的功能和用法。

> 例如：
>
> 通过调用此接口实现XXX功能需求的数据交互。

### URL

```http
POST rdsBaseUrl/interface-template1
```

【请求参数（Params）】

``根据实际的需求，和客户协商``，格式如下。

> 如果没有请求参数的需求，需说明 **无请求参数**。

| 参数名称 | 参数描述 | 数据类型 | 必填 | 备注 |
| :------: | :------: | :------: | :--: | ---- |
|    -    |    -    |    -    |  -  | -    |

调用接口时，示例为 `http://host:8080/api/interface-template1` 。

### 请求正文（RequestBody）

``根据实际的需求，和客户协商``，格式如下。

> 如果没有请求参数的需求，需说明 **无请求正文**。

| 参数名称 | 参数描述 | 数据类型 | 必填 | 备注 |
| :------: | :------: | :------: | :--: | ---- |
|    -    |    -    |    -    |  -  | -    |

### 响应（Response）

【响应正文（ResponseBody）】

``根据实际的需求，和客户协商``，格式如下。

| 字段名称 |  字段描述  | 数据类型 | 必填 | 备注                                                                                 |
| :------: | :--------: | :------: | :--: | ------------------------------------------------------------------------------------ |
| field-1 | 字段描述-1 |  字符串  |  是  | field-1 的备注。例如：
无论请求成功与否，值都为 `"value-1"` 。                |
| filed-2 | 字段描述-2 |  布尔值  |  是  | field-2 的备注。例如：
请求成功时，值为 `true` ；请求失败时值为 `false` 。  |
| field-n | 字段描述-n |   数值   |  是  | field-3 的备注。例如：
请求成功时，值为 `10000` ；请求失败时值为 `10001` 。 |

- 请求成功时，响应码（ResponseCode）为 200 ，响应正文为 JSON 格式的数据，示例如下：

  ```json
  {
      "field-1": "value-1",
      "field-2": true,
      "field-n": 10000
  }
  ```
- 请求失败时，响应码（ResponseCode）为 400 ，响应正文为 JSON 格式的数据，示例如下：

  ```json
  {
      "field-1": "value-1",
      "field-2": false,
      "field-n": 10001
  }
  ```

### Postman 示例

``添加 Postman 的调试截图``。

## 模板2 - 只要求请求正文

### 接口描述

简要的描述这个接口的功能和用法。

### URL

```http
POST rdsBaseUrl/interface-template2
```

【请求参数】

``根据实际的需求，和客户协商``，格式如下。

| 参数名称 | 参数描述 | 数据类型 | 必填 | 备注 |
| :------: | :------: | :------: | :--: | ---- |
|    -    |    -    |    -    |  -  | -    |

调用接口时，示例：`http://host:8080/api/interface1-template2` 。

### 请求正文（RequestBody）

``根据实际的需求，和客户协商``，格式如下。

| 参数名称 |  参数描述  | 数据类型 | 必填 | 备注                                              |
| :------: | :--------: | :------: | :--: | ------------------------------------------------- |
|  arg-1  | 参数描述-1 |  字符串  |  是  | arg-1 的备注。例如：默认值为 `"arg-value-1"` 。 |
|  arg-2  | 参数描述-2 |   数值   |  是  | arg-2 的备注。例如：默认值为 `1` 。             |
|  arg-n  | 参数描述-n |  字符串  |  是  | arg-2 的备注。例如：默认值为 `"arg-value-n"` 。 |

请求正文为 JSON 格式的数据，示例如下：

```json
{
    "arg-1": "arg-value-1",
    "arg-2": 1,
    "arg-n": "arg-value-n"
}
```

### 响应（Response）

【响应正文（ResponseBody）】

``根据实际的需求，和客户协商``，格式如下。

| 字段名称 |  字段描述  | 数据类型 | 必填 | 备注                                                                                 |
| :------: | :--------: | :------: | :--: | ------------------------------------------------------------------------------------ |
| field-1 | 字段描述-1 |  字符串  |  是  | field-1 的备注。例如：
无论请求成功与否，值都为 `"value-1"` 。                |
| filed-2 | 字段描述-2 |  布尔值  |  是  | field-2 的备注。例如：
请求成功时，值为 `true` ；请求失败时值为 `false` 。  |
| field-n | 字段描述-n |   数值   |  是  | field-3 的备注。例如：
请求成功时，值为 `10000` ；请求失败时值为 `10001` 。 |

- 请求成功时，响应码（ResponseCode）为 200 ，响应正文为 JSON 格式的数据，示例如下：

  ```json
  {
      "field-1": "value-1",
      "field-2": true,
      "field-n": 10000
  }
  ```
- 请求失败时，响应码（ResponseCode）为 400 ，响应正文为 JSON 格式的数据，示例如下：

  ```json
  {
      "field-1": "value-1",
      "field-2": false,
      "field-n": 10001
  }
  ```

### Postman 示例

`此处`添加 Postman 的调试截图 ``。

效果图：