一套程序员用的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 的调试截图 ``。
　　效果图：