接口文档怎么写：从代码生成 API 接口文档提示词（参数表、返回示例、错误码 + OpenAPI）
后端写完接口要交给前端、测试或第三方对接时用：贴上路由和处理函数代码，生成按统一模板整理的接口文档（含参数约束、返回示例、错误码、鉴权说明），并可同时输出 OpenAPI 3 草稿，导入 Apifox、Postman 等工具。
通用大模型 对话模型通用
【角色】你是一名同时做过后端和对外开放平台的技术文档工程师，知道对接方最常问的是：要不要登录、哪些字段必填、出错返回什么、能不能重试。 【背景】 - 服务与框架：[框架，如 Spring Boot/FastAPI] - 文档读者：[前端/测试/外部合作方] - 统一的返回结构与错误码约定（没有就写无）：[统一返回结构] - 鉴权方式：[如 Bearer Token/Cookie/签名] - 接口代码（路由定义、请求模型、处理函数、相关的数据模型）： [粘贴接口代码] 【任务】对每个接口输出： 1. 基本信息：接口名称、用途一句话、请求方法与路径、是否需要登录及所需权限。 2. 请求参数表：位置（path/query/header/body）| 字段 | 类型 | 必填 | 默认值 | 取值约束（长度、范围、枚举、格式）| 示例 | 说明。嵌套对象用「父字段.子字段」展开。 3. 请求示例：curl 一条 + JSON 请求体。 4. 成功响应：字段表 + JSON 示例；分页接口写清分页参数、最大页大小和排序规则。 5. 错误响应：HTTP 状态码 | 业务错误码 | 触发条件 | 调用方应如何处理。 6. 调用须知：幂等性（重复提交会怎样）、是否可安全重试、频率限制、时间字段的时区与格式、金额单位。 7. 最后输出这些接口的 OpenAPI 3.0 YAML 草稿。 【约束】 - 只写代码里能看出来的信息；代码中看不出的（如频率限制、权限名），写「待确认」并汇总到最后，不要猜测。 - 示例数据使用明显虚构的值，不出现真实手机号、邮箱、密钥。 - 发现代码与常见规范不一致的地方（如 GET 接口修改数据、错误时仍返回 200、缺少参数校验），在文末「接口设计建议」里单独列出，不要擅自改写文档掩盖问题。 【输出格式】 Markdown：每个接口一个二级标题，按上面 1–6 的顺序；然后是 OpenAPI YAML 代码块；最后是「待确认」和「接口设计建议」两个清单。
高亮处换成你自己的内容：[前端/测试/外部合作方]、[统一返回结构]、[粘贴接口代码]
ChatGPT Plus 充值
已被复制 0 次
使用说明
怎么填变量：只贴路由函数不够，要连同请求/响应的数据模型（DTO、Pydantic 模型、校验注解）一起贴，参数约束全靠它们推断。[文档读者] 是外部合作方时，模板会更强调鉴权、签名、重试和错误处理；给内部前端看则可以简略。
常见坑：
- 代码里没写的东西（频率限制、权限点）AI 很容易「合理补全」，一定要看「待确认」清单逐条核对。
- 分页接口要写清 page 从 0 还是 1 开始，这是对接中最常见的扯皮点。
- 金额、时间字段务必写明单位和时区，例如「金额单位为分」「时间为 ISO 8601，带时区」。
追问技巧：生成后追问「站在前端角度，按这份文档对接还缺什么信息」；接口改动后把 diff 贴回去，说「只更新受影响的字段，并在文档开头加一条变更记录」。
示例输出
示例，仅供参考（节选）
GET /api/orders/{id} 查询订单详情（需要登录，只能查看自己的订单）
| 状态码 | 业务码 | 触发条件 | 调用方处理 |
|---|---|---|---|
| 401 | AUTH_REQUIRED | 未登录或 token 过期 | 跳转登录 |
| 404 | ORDER_NOT_FOUND | 订单不存在或不属于当前用户 | 提示「订单不存在」 |
yaml
openapi: 3.0.3
info:
title: 订单服务
version: 1.0.0
paths:
/api/orders/{id}:
get:
summary: 查询订单详情
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: 成功
'404':
description: 订单不存在或不属于当前用户
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer同款作品
用这条提示词做出来的作品；原作者会因此获得积分
还没有同款，来做第一个。
0 条评论
还没有评论，来抢沙发～