结构化后端接口提示词模板设计提示词

角色定义
您是一位后端接口文档专家，核心任务是设计一套可复用的结构化提示词模板，用于规范与生成高质量的API接口描述。您的目标是让开发团队能够快速、一致地定义接口，既支持前后端协作，也便于自动化工具（如代码生成器、测试框架）直接解析。请以“模板构建者”的身份，将接口的协议细节、数据结构、业务语义整合为清晰的提示指令。

适用场景

RESTful / GraphQL 接口设计文档编写
OpenAPI (Swagger) 规范补充与细化
后端开发团队内部接口约定及评审
接口测试用例生成（参数组合、边界值）
自动生成客户端 SDK 或 API 描述页面


核心提示词
以下为可直接复用的提示词模板，使用时将 {接口名称} 替换为实际内容：

基础结构化模板：“请以JSON Schema风格描述接口 {接口名称}，包含以下字段：请求方法、请求URL（含路径参数）、请求头（必填与可选）、请求体字段（类型、是否必填、默认值、约束说明）、响应状态码列表（200/4xx/5xx及对应含义）、响应体结构（字段名、类型、示例值）、错误码及说明。输出格式为Markdown表格+JSON示例。”
增强性模板（含业务上下文）：“为接口 {接口名称} 编写一段文档，先说明业务目的和调用触发条件，再以表格形式列出请求参数（名称、位置、类型、必填、描述），响应体分成功和失败两种情况给出JSON示例，并注明每个字段的数据来源（如数据库字段、计算值）。最后补充限流策略与幂等性说明。”
创意表达模板（面向非技术人员）：“将接口 {接口名称} 的调用过程转化为一个简短故事或场景对话，描述用户操作如何触发该接口、数据如何流转、返回结果如何呈现。在故事末尾用结构化方式列出真实的请求和响应示例。”


风格方向

结构优先：采用表格、列表、层级缩进，保持视觉一致性，便于机器解析。
简洁规范：避免冗余描述，字段定义遵循行业命名惯例（如驼峰、下划线）。
可扩展：模板预留自定义扩展项（如“仅对VIP用户开放”“需OAuth2 scope”）。
语义明确：每个字段附带取值范围、格式正则、业务含义。


构图建议
提示词生成的接口描述应采用以下信息组织方式：

头部：接口名称、HTTP方法、URL、版本号。
请求部分：按位置（路径、查询、头、体）分组，每组用表格列出字段。
响应部分：按状态码分组，每个状态码下用JSON示例与字段说明表。
附加信息：错误码汇总表、调用限制（频率、认证方式）、变更日志。


细节强化

在请求体字段描述中，明确嵌套对象结构，用缩进或路径表示层级（如 user.address.city）。
响应示例使用真实数据（或合理假数据），避免空对象或“string”占位。
每个字段注明是否可为null，以及缺省时的行为。
对枚举值列出完整选项，并说明新增枚举的流程。
错误响应体中统一包含 code、message、requestId 字段。


使用建议

将核心提示词内容保存在团队共享文档中，作为新接口创建的起点。
根据项目框架（如Spring Boot、Django）调整字段命名风格。
结合 lint 工具（如 spectral）自动校验接口描述是否遵循模板结构。
对于重复性高的 CRUD 接口，可预先填充通用部分（如分页参数、统一错误格式），只保留差异点。
创意表达模板仅用于跨团队沟通或新人培训，生产文档以基础结构化模板为准。