Gemini接口返回示例转字段说明提示词的两个方向

先明确一个核心结论：要让Gemini在生成接口文档时，自动把返回的JSON示例拆解成字段级说明，并且同时输出两种不同组织逻辑的提示词——一种严格按JSON字段的原始顺序展开，另一种则按业务语义进行分组归类。关键是这两种提示词不能只是换词重述，必须在结构意图上体现出本质差异。

方向一：按JSON字段原始顺序生成字段说明提示词

第一步，将接口返回的完整JSON示例复制过来，确保真实值完整呈现，例如{"code":0,"data":{"id":123,"name":"张三"}}。省略号或占位符会让Gemini推断失误，必须用实际数值填充。

第二步，在提示词开头明确指令：“请严格按照下列JSON响应体，按照字段在原文中出现的顺序，依次提取字段名、数据类型、含义、是否必填、示例值，生成字段说明表。顺序不可调整，字段不可合并，空字段也不得跳过。”指令越具体，Gemini越能精准执行。

第三步，粘贴JSON示例后，追加一条关键约束：若某字段值为对象或数组，必须递归展开一级子字段（例如data对象下的id和name必须单独列为两条记录）。这一步极易遗漏，一旦子字段未展开，文档就会缺失关键信息。

方向二：按业务语义分组生成字段说明提示词

方法一，用角色指令锚定分组逻辑。直接告诉Gemini：“你是一位电商系统API文档工程师，负责将技术响应转化为业务方能理解的说明。请识别该JSON中隐含的3～5个业务实体（如‘订单主信息’‘收货地址’‘优惠详情’），把字段分配到最匹配的实体下，每个实体内字段按重要性降序排列。”这样Gemini会带着业务视角重新组织信息。

方法二，提供分组关键词引导。在JSON示例之后直接给出分组线索：“请按以下四类组织字段说明：① 状态控制类（code、msg、success）；② 主体数据类（user、order、product相关字段）；③ 时间与审计类（created_at、updated_by）；④ 扩展配置类（extra、metadata）。不属于这四类的字段归入‘其他’。”注意，分组名称必须使用业务术语，避免“第一层字段”“嵌套字段”等技术表述，否则业务方难以理解。

关键区别验证步骤

拿到Gemini的输出后，立即执行三项验证：

第一，核对字段总数是否与原始JSON扁平化后的字段数一致——若数量偏少，说明字段被遗漏，必须调整提示词。

第二，对比两个方向的输出：方向一的首条字段必须是JSON最顶层第一个键（通常是code或status），方向二的首组标题必须是业务名词（例如“用户身份信息”），而非“技术层级描述”。

第三，随机选取一个嵌套字段（如data.address.city），确认方向一中它出现在data之后、address之后、city单独成行；方向二中它必须归属在“收货地址”或类似业务组下，绝不能与data或address并列展示。这是验证两个方向是否真正执行到位的核心环节。

来源：互联网