api-doc-template

name	api-doc-template
description	Provides API documentation template and standards for RESTful API, gRPC, and other interfaces. Includes request/response format, parameter definitions, error codes, and Markdown documentation structure. Invoke when generating API documentation or interface specifications.

API文档模版规范

本技能提供标准化的API接口文档模版，适用于RESTful API、gRPC等主流接口规范。确保接口文档结构清晰、内容完整、术语准确。

接口文档规范

标准模版格式

##### 简要描述

- 获取全部摄像头报警

##### 请求URL
- `/Api/V1_0/AppAdmin/CameraReportPolice/GetAllCameraReportPoliceTable`

##### 请求方式
- POST

##### 参数

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|token |是  |string |企业用户token   |

##### 请求示例

```json
{
    "iStart": 0,
    "iLength": 10,
    "data": {}
}

返回示例

{
    "code": 0,
    "message": "",
    "data": {
        "allSize": 1,
        "pageSize": 1,
        "list": [
            {
                "cameraReportPoliceEventType": ""
            }
        ]
    }
}

返回参数说明

参数名	类型	说明
code	int	返回码
message	String	返回码描述
data		返回数据
allSize	int	全部数据数量

## 文档规范要求

### 1. 简要描述
- 简洁明了地说明接口功能
- 使用动词开头，如"获取"、"保存"、"删除"等
- 避免使用过于技术化的术语

### 2. 请求URL
- 完整的接口路径
- 使用代码块格式包裹
- 包含版本号（如V1_0）

### 3. 请求方式
- 明确HTTP方法：GET、POST、PUT、DELETE
- 使用列表格式
- 与实际接口实现保持一致

### 4. 参数说明表格
|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |

- **参数名**：参数的名称，使用小驼峰命名
- **必选**：是/否，标识参数是否必须
- **类型**：string、int、boolean、object、array等
- **说明**：参数的业务含义和取值范围

### 5. 请求示例
- 使用JSON代码块格式
- 提供完整的请求示例
- 包含所有必选参数
- 可选参数可以省略或提供默认值

### 6. 返回示例
- 使用JSON代码块格式
- 提供完整的返回示例
- 包含成功和失败的示例（如有必要）
- 数据结构清晰，便于理解

### 7. 返回参数说明表格
|参数名|类型|说明|
|:-----  |:-----|-----                           |

- **参数名**：返回参数的名称
- **类型**：参数的数据类型
- **说明**：参数的业务含义

## 常用返回码规范

|返回码|说明|
|:-----  |:-----                           |
|0 |成功  |
|-1 |系统异常  |
|-2 |参数错误  |
|-3 |未登录  |
|-4 |无权限  |
|-5 |数据不存在  |

## 特殊场景处理

### 分页接口
- 请求参数包含：iStart（起始位置）、iLength（每页数量）
- 返回数据包含：allSize（总数量）、pageSize（当前页数量）、list（数据列表）

### 列表查询接口
- 请求参数包含：data对象，包含查询条件
- 返回数据包含：allSize（总数量）、list（数据列表）

### 文件上传接口
- 请求方式：POST
- Content-Type：multipart/form-data
- 请求示例需要说明文件字段名

### 文件下载接口
- 请求方式：GET
- 返回类型：文件流
- 需要说明文件名和格式

## 文档命名规范

- 接口文档文件名使用中文
- 格式：功能名称.md
- 示例：获取全部摄像头报警.md

## 文件存储规范

- 接口文档存储在：`doc/接口文档/` 目录下
- 按业务模块分类存放
- 文件名与接口功能对应

## 注意事项

1. **参数验证**：所有参数必须说明是否必选、数据类型、取值范围
2. **返回码**：必须说明所有可能的返回码及其含义
3. **示例完整**：请求和返回示例必须完整、真实可用
4. **术语统一**：文档中使用的术语必须与代码保持一致
5. **版本管理**：接口变更时需要更新文档版本号
6. **错误处理**：必须说明异常情况下的返回格式和错误信息