一、适用问题
如何编写符合规范的GPT接口文档？
二、准备资料
需准备接口定义、请求参数、响应格式、错误码等基础信息。
三、具体步骤
1. 明确接口规范：定义API版本、请求方法、URL路径。
2. 列出请求参数：包括必填项、可选项、数据类型。
3. 构建响应结构：描述成功与错误响应的格式及内容。
4. 设计错误码体系：为不同错误类型分配唯一码及描述。
5. 编写文档说明：包含使用场景、调用示例、注意事项。
四、虚构示例
原始输入：
"接口名称": "用户登录",
"请求方法": "POST",
"URL路径": "/api/v1/login",
"请求参数": {
"username": "string",
"password": "string",
"grant_type": "string"
},
"响应格式": {
"code": "integer",
"message": "string",
"data": "object"
},
"错误码": {
"400": "无效凭证",
"401": "未授权",
"500": "服务器内部错误"
}
完整提示词：
"请根据以下接口定义生成详细版接口文档：
接口名称：用户登录
请求方法：POST
URL路径：/api/v1/login
请求参数：
- username: 必填, 字符串类型
- password: 可选, 字符串类型
- grant_type: 必填, 字符串类型
响应格式：
- code: 整数类型, 200表示成功
- message: 字符串类型, 说明状态信息
- data: 对象类型, 包含用户信息
错误码：
- 400: 无效凭证
- 401: 未授权
- 500: 服务器内部错误
请确保文档结构清晰，包含接口说明、参数说明、响应说明、错误码说明，并提供调用示例。"
示例输出：
用户登录接口文档
接口说明：用于用户登录操作
请求方法：POST
URL路径：/api/v1/login
请求参数：
- username: 必填，用户名
- password: 可选，密码
- grant_type: 必填，授权类型
响应格式：
- code: 200表示成功
- message: 登录成功/失败信息
- data: 包含用户ID、昵称等信息
错误码说明：
- 400：无效凭证
- 401：未授权
- 500：服务器错误
调用示例：
POST /api/v1/login
参数：
username: admin
password: 123456
grant_type: authorization_code
响应：
code: 200
message: 登录成功
data: {
"userId": "67890",
"nickname": "admin"
}
五、核对清单
1. 接口名称是否准确？
2. 请求方法是否正确？
3. URL路径是否完整？
4. 请求参数是否齐全？
5. 响应格式是否清晰？
6. 错误码是否对应？
7. 文档结构是否合理？
8. 是否提供调用示例？
六、常见误区
1. 忽略错误码说明，导致用户理解困难。
2. 参数说明不明确，影响调用准确性。
3. 响应格式过于简略，无法判断状态。
4. 文档缺乏示例，用户难以参考。
5. 接口名称与描述不一致，影响使用体验。
6. 不分版本或时间，导致信息过时。
7. 不说明调用方式（如是否需认证），影响使用。
8. 不提供使用场景或注意事项，影响实际应用。