تشغيل أي مهارة في Manus بنقرة واحدة

api-doc-template

النجوم٣٦

التفرعات١٠

آخر تحديث٥ فبراير ٢٠٢٦ في ٠٧:١٥

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.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

jie023

jie023/trae-setting

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو الويبمهن الحاسوب والرياضيات·SOC 15-1254

SKILL.md

readonly

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. **错误处理**：必须说明异常情况下的返回格式和错误信息

المزيد من هذا المستودع

نفس المستودع

requirement-doc-template

jie023/trae-setting

Complete PRD template with AI-friendly markers. Use for product requirement docs: includes overview, requirements, processes, data, interfaces, acceptance. AI can quickly identify [AI] marked sections for implementation.

2026-02-0536

database-design-template

jie023/trae-setting

Provides database design templates and documentation structure. Invoke when designing database schemas, creating database design documents, or generating SQL scripts.

2026-02-0536

java-common-standards

jie023/trae-setting

Provides common Java coding standards including hutool tool usage and Lombok annotations. Invoke when generating Java code (DO, VO, Service, Controller) or applying coding standards.

2026-02-0536

java-controller

jie023/trae-setting

Provides Java Controller layer standards including RESTful API design, request mapping, parameter validation, and response handling. Invoke when generating Controller files or RESTful API endpoints.

2026-02-0536

java-dao

jie023/trae-setting

Provides Java DAO layer standards including interface specifications, MyBatis XML templates, method naming, parameter annotations, and CRUD operation patterns. Invoke when generating DAO files or MyBatis mappers.

2026-02-0536

java-do

jie023/trae-setting

Provides database type to Java type mapping standards for DO (Data Object) generation. Includes type conversion rules and special field handling. Invoke when generating DO files from SQL table structures.

2026-02-0536

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. **错误处理**：必须说明异常情况下的返回格式和错误信息