我平时写接口、维护文档，最怕的是代码改了文档没跟上。后来我开始用API文档生成提示词，把接口信息喂给大模型，让它先出一版文档草稿，我再逐项核对。这个做法不算魔法，它更像一份写给模型的“写作说明书”。
我理解的API文档生成提示词，就是一段自然语言指令。里面会交代清楚：你要扮演什么角色，根据哪些接口信息写文档，输出成什么结构，字段说明写到什么颗粒度，异常情况怎么描述。它和直接让模型“帮我写个文档”不一样，它把上下文、格式、约束都尽量说透。
从开发者的角度看，提示词是接口描述和文档结果之间的转换器。从文档维护者的角度看，它是一套可复用的写作模板。我见过有人把它当成代码生成器，结果模型编出根本不存在的字段，这个坑后面会细说。
1.1 什么是API文档生成提示词
我先把话放这儿：API文档生成提示词不是一段固定咒语，它更像你给一位新同事交代任务。你要告诉他接口是干什么的，请求方法、路径、参数、返回值长什么样，文档要写给谁看，哪些内容必须保留，哪些内容不能瞎编。模型拿到这些信息，才会按你的意图输出。
我通常会把提示词拆成几块来写。角色设定放前面，比如“你是一位资深后端工程师，擅长写清晰的接口文档”。接口输入信息放中间，把接口描述、字段表、示例请求响应贴进去。输出格式放后面，明确标题层级、字段表格、示例代码块。约束条件也别忘了写，比如“不要补充未提供的字段”“异常码按给定列表输出”。
有个场景我印象很深。团队里一位前端同事要对接新接口，后端只给了一段粗糙的接口说明。我把那段说明整理成提示词，让模型生成文档初稿。前端同事看完说，字段含义和示例比原来清楚多了。提示词在这里干的事，是把零散信息组织成可读文档，不是替代人做业务判断。
1.2 为什么使用提示词生成API接口文档
手写接口文档的痛，我估计很多同行都懂。字段一多，表格容易漏；示例一改，文档容易旧；新人接手项目，文档和代码对不上。用提示词生成API接口文档，最大的好处是快。我把接口定义、字段说明、请求响应示例贴进提示词，模型几分钟就能给出结构完整的草稿。
我见过小团队用这个办法快速补文档。后端开发改完接口，顺手把变更点写进提示词，模型生成一版更新说明，前端和测试直接看。大团队也能用，把团队规范写进提示词，生成出来的文档风格更统一。这里的关键是“草稿”两个字，模型负责组织语言和格式，人负责确认业务逻辑和字段准确性。
说直白点，提示词生成文档省的是重复劳动，不是省掉审核。我遇到过一次，模型把“用户ID”写成了“用户编号”，意思差不多，但和系统里的字段名不一致。这种细节必须人工过一遍。我现在的习惯是，生成完先对字段名，再看示例能不能跑通，最后检查异常说明有没有漏。
1.3 典型应用场景与能力边界
我常用它的场景有这么几个。新接口写完，先让模型出一版文档初稿，我再补业务背景和注意事项。老接口缺文档，我把代码里的注释和参数结构整理进提示词，让模型帮忙补全字段说明。还有多语言文档，同一套接口信息换一种输出语言，提示词里加一句“用英文输出”，能省不少翻译时间。
能力边界也很明显。模型不熟悉你们内部的鉴权规则、限流策略、灰度逻辑，这些内容它编不出来，也不该让它编。复杂业务状态机、跨服务调用顺序、性能压测结论，这些需要人写清楚。我踩过的坑是，提示词里没给错误码列表，模型自己编了几个“常见错误”，看着像那么回事，实际对不上。
我现在的做法是，提示词里明确写“只根据以下信息生成，不要补充未提供的字段和错误码”。接口示例尽量给全，请求头、查询参数、请求体、响应体、异常响应都贴上。模型生成能力强，但它需要边界。边界给清楚了，文档质量会稳很多。
2. API文档生成提示词的核心构成
上一章聊了提示词是什么、为什么值得用。这一章我拆开讲一份能落地的API文档生成提示词里到底放哪些块。我自己写提示词习惯按四层来搭：角色和目标、输入信息、输出格式、约束条件。少一层，生成结果就容易飘。四层都写清楚，模型才知道该站在谁的角度说话、拿什么材料写、写成什么样子、哪些红线不能碰。
2.1 角色设定与生成目标
角色设定不是走形式。我试过同一份接口信息，一份提示词开头写“你是一位资深后端工程师，写文档偏重字段含义和异常处理”，另一份写“你是一位技术文档写作者，语言简洁、面向外部开发者”。出来的文档差别肉眼可见。前者会把鉴权、错误码、边界条件写得更细，后者更注重可读性和整体结构。角色给模型定了一个视角，它后面组织内容时会顺着这个视角走。我一般会根据文档读者来选角色，内部对接就选后端工程师，对外开放就选技术文档写作者。
生成目标要写到具体场景里，别只写“帮我生成API文档”。这句话太宽，模型不知道详略怎么分配。我通常写成“读者是刚接手项目的前端，字段说明需要包含类型、是否必填和枚举值含义，示例要给curl和JSON两种”。目标越具体，模型越知道哪些内容该展开、哪些可以带过。说个真事，有一次我只写了“生成接口文档”，模型把返回字段解释得像产品说明书，前端同事看完还是不知道分页参数怎么传。后来我在目标里补了一句“重点说明分页、排序和筛选参数的使用方式”，文档可用性明显上来了。
角色和目标放在提示词最前面，我一般控制在两三句话。写多了会挤占输入信息的空间，写少了又定不住调子。我的习惯是先写角色一句话，再写目标一句话，中间用“你的任务是”连起来。这样模型读起来顺，后面贴接口信息时也不容易跑偏。
2.2 接口输入信息的组织与上下文补充
接口输入信息我坚持按接口维度分块列。路径、请求方法、请求头、查询参数、请求体字段、响应体字段、错误码，各占一块。不要一大段散文丢进去，模型读散文容易漏字段。我习惯用表格或者YAML片段来贴，字段名、类型、是否必填、说明各占一列。表格比纯文字清楚，模型提取字段关系时更稳。有一次我偷懒，把参数说明写成一段话，模型生成出来的字段表少了两个可选参数，前端联调时才发现。
上下文补充是很多人容易忽略的一块。模型不知道你们系统的业务背景，比如“订单状态”字段有哪几个枚举值、每个值代表什么、“用户等级”和“折扣”之间是什么关系。这些信息要在输入区补一句。我还会把鉴权方式、环境地址、接口版本号写进去，这些内容模型不会自己编，但文档里缺了又不行。补充上下文不用长篇大论，一两句话点清楚就行。比如“status取值：0待支付、1已支付、2已发货、3已完成”，模型就能把枚举说明写进字段表。
我踩过的坑是只给请求体示例，没给字段说明表。模型看着示例自己猜字段含义，把“amount”解释成“数量”，实际是金额。还有一次它把“type”字段写成“类型”，没提具体枚举，文档等于没写。我现在的做法是字段表和示例一起给，字段表管准确性，示例管可读性。两个材料对齐了，模型输出质量会稳很多。
2.3 输出格式与文档结构约束
输出格式必须写死。我一般要求模型输出Markdown，一级标题写接口名称，二级标题固定为“接口说明”“请求参数”“响应参数”“请求示例”“响应示例”“错误码”。字段表格的列名也定好：字段名、类型、必填、说明、示例值。模型有时候会自由发挥，加一个“注意事项”章节放在最后，这个可以允许，但要限定位置，不能插在参数表和示例中间。格式约束写清楚，生成结果才能直接贴进文档系统。
结构约束要贴合团队现有的文档规范。我们团队的习惯是每个接口文档开头先写一句业务用途，再列请求方法加路径。提示词里我就写“文档开头用一句话说明接口用途，紧接着给请求方法和路径，参数表放在路径下面”。这样模型不会把业务说明藏到文档末尾。我试过给一个完整的输出模板样例，让模型照着填，效果比纯文字描述稳定得多。模板里留占位符，比如“{{接口名称}}”“{{字段表}}”，模型知道哪里填什么，不会自己发明章节。
还有一点，输出格式里要指定示例代码块的语言标记。写“请求示例用bash代码块包curl命令，响应示例用json代码块”。不指定的话，模型有时给纯文本示例，有时给python请求代码，前端同事看着别扭。格式约束不用写太长，但关键位置要卡住。我一般把输出格式放在输入信息后面，角色和目标放前面，约束条件放最后。这个顺序模型读起来顺，生成时也容易按部就班。
2.4 约束条件、异常说明与质量要求
约束条件要写禁止项。我常用的几句是：“不要补充未提供的字段和错误码”“不要修改字段名的大小写”“不要合并多个接口到一个文档里”“示例值必须符合字段类型”。这些话说出来，模型编造字段的概率会降不少。我遇到过一次，提示词里没写禁止编造错误码，模型自己加了“401未授权”“500服务器错误”，看着合理，实际和我们系统的错误码对不上。后来我把错误码列表贴全，又加了一句“只输出以下错误码”，问题就没了。
异常说明要单独列，不能只写成功响应。提示词里我专门写一段：“必须输出异常响应示例，并附错误码表，包含HTTP状态码、业务错误码、错误信息、触发场景。”模型默认偏向写成功路径，异常部分容易一笔带过。你明确要求了，它才会认真列。错误码表我一般让模型放在文档末尾，和响应参数表分开，避免混在一起看花眼。触发场景那一列要写具体，比如“token过期”“参数缺失”“余额不足”，不要只写“请求错误”。
质量要求可以写几条自查规则。我常加的是：“字段说明避免循环定义，比如‘用户ID’不能解释成‘用户的ID’”“同一字段在不同接口中的描述保持一致”“生成后自查字段表和示例是否对应”。模型输出前会顺着这些规则过一遍，虽然不能百分百靠谱，但明显错误会少很多。我还会要求“字段说明里写清楚单位”，比如金额单位是元还是分、时间格式是时间戳还是ISO字符串。这些细节不写，文档交付后还得返工。约束条件、异常说明、质量要求这三块放在提示词末尾，像一道检查清单，模型生成时会拿它们当边界。
这几块凑齐了，提示词才算能干活。角色和目标定方向，输入信息给材料，输出格式卡结构，约束条件兜底。我现在的习惯是每次生成前快速过一遍这四块，缺哪块补哪块。补得越全，后面人工核对越省力。
3. API文档生成提示词模板与ChatGPT实操
上一章把提示词的四个核心模块拆开讲了。这一章我把它们拼成一个能直接拿去用的模板，再拿ChatGPT实际跑一遍。我平时写提示词不爱从零开始，手里有几个固定模板，改改占位符就能上手。模板这东西，写得糙一点没关系，关键是把结构卡住，让模型每次都在同一条轨道上跑。
3.1 通用API文档生成提示词模板
我常用的通用模板长下面这样，直接贴出来：
你是一位{{角色}}，你的任务是为以下接口生成一份面向{{读者}}的API文档。
接口基本信息：
- 接口名称：{{接口名称}}
- 请求方法：{{请求方法}}
- 请求路径：{{请求路径}}
- 业务用途：{{业务用途}}
- 鉴权方式：{{鉴权方式}}
请求参数：
{{请求参数表}}
响应参数：
{{响应参数表}}
错误码：
{{错误码表}}
补充上下文：
{{业务背景、枚举值说明、字段间关系}}
输出要求：
1. 使用Markdown格式输出
2. 文档结构依次为：接口说明、请求参数、响应参数、请求示例、响应示例、错误码
3. 参数表列名固定为：字段名、类型、必填、说明、示例值
4. 请求示例用bash代码块包curl命令，响应示例用json代码块
5. 只输出上述错误码，不要自行添加
6. 字段说明避免循环定义，写清单位和格式
这个模板不是死的。我有时候会把“补充上下文”挪到请求参数前面，因为有些接口的枚举值说明太长，放在后面模型容易漏看。也试过在输出要求里加一条“文档开头用一句话说明接口用途”，效果也不错。模板的价值在于把四层结构固化成骨架，用的时候按接口情况微调就行。我刚开始用的时候总想一次写完美，后来发现先跑一版再补约束，比憋半天写一个“完美模板”效率高得多。
模板里我特意没写“请”“麻烦”这类客套话。模型不吃这套，写多了反而稀释关键信息。祈使句加清单式约束，模型读起来更利索。有一次我帮同事改提示词，他开头写了三行“请你作为一名专业的文档工程师，帮我认真仔细地生成一份高质量的API文档”，我全删了，换成“你是一位技术文档写作者，为以下接口生成API文档”，生成质量没降，token还省了。
3.2 ChatGPT生成API接口文档提示词设计
ChatGPT和别的模型有个不一样的地方：它上下文窗口大，但容易“过度热情”。你给一段接口描述，它有时候会自己补一堆你没要求的章节，比如“安全注意事项”“性能优化建议”。这些东西不是不能要，但放在接口文档里容易冲淡核心信息。我在ChatGPT上用的提示词会多加一条：“严格按输出要求的结构输出，不要添加未列出的章节。”
另一个经验是，ChatGPT对表格的还原能力比纯文本强。我喂参数的时候尽量用Markdown表格或者YAML片段，别用“参数有id、name、age，其中id是必填的”这种散文。散文丢进去，ChatGPT提取字段关系时容易串行。我做过一次对比，同样的接口信息，散文版生成出来的参数表漏了两个可选字段，表格版一个没漏。从那以后我养成了习惯，接口信息先在表格里理一遍再贴进提示词。
ChatGPT还有个毛病是示例值爱编。你给字段“amount”类型是decimal，它示例值写“100.00”，看着合理，但你们系统实际单位是分，传100.00就错了。我在提示词里会专门写一句：“示例值必须符合字段说明中的单位和格式。”有时候还会直接给出示例值，不让它自由发挥。比如“amount示例值填1000，单位分”。这样它就不会自作主张。说白了，ChatGPT像个反应快但不太细心的实习生，你得多给具体例子，少给它留想象空间。
对话轮次上我一般控制在两到三轮。第一轮贴模板和接口信息让它出初稿，第二轮拿初稿挑毛病让它改。第三轮基本就是微调措辞了。轮次太多它容易把前面的约束忘掉，尤其是输出格式那几条。我试过连续改五轮，到第四轮它把错误码表的位置挪到了响应参数前面，还自己加了个“版本历史”章节。后来我学乖了，每轮开头把关键约束再贴一遍，哪怕重复。
3.3 从接口描述到文档输出的示例演示
拿一个用户查询接口来走一遍。原始信息是产品经理丢过来的一段话：“查用户信息的，GET /api/v1/users/{id}，需要token，返回id、name、email、status、created_at。status是0正常1禁用2注销。id是数字，name字符串，email字符串，created_at时间戳。”
这段信息直接丢给ChatGPT，它也能生成，但字段说明会很薄。我按模板整理一遍：
角色写“技术文档写作者”，读者写“对接前端”，业务用途写“根据用户ID查询用户详细信息”。请求参数表里id放路径参数，类型integer，必填是，说明“用户唯一标识”。响应参数表五个字段各一行，status的说明里带上枚举值。补充上下文写一句“created_at为Unix时间戳，单位秒”。错误码我给了三个：401 token无效、404用户不存在、500服务器内部错误。
提示词组装好贴进ChatGPT，第一版输出结构基本对，但有两个小问题。一个是它在请求示例里用了curl -X GET，没带Authorization头。我在第二轮补了一句“请求示例必须包含Authorization请求头，格式为Bearer {token}”。另一个是status字段的说明它写成了“用户状态”，枚举值没带上。我补了一句“status字段说明必须包含枚举值含义”。第三轮微调了一下created_at的示例值格式，就定稿了。
整个过程从整理信息到定稿大概十分钟。手写这份文档差不多也要这么久，但生成版的结构更统一，字段表不会漏列。我现在的做法是生成完快速扫一遍字段表和示例对不对应，对应上了就直接贴进文档系统。对不上的地方回ChatGPT改一轮，比手敲省事。
3.4 模板复用与变量占位符设计
模板复用的关键是把变化的部分抽成占位符，不变的部分写死。我上面那个模板里，{{角色}}、{{接口名称}}、{{请求参数表}}这些是变量，输出要求那六条是固定约束。每次用的时候只换变量，约束不动。这样既省事，又能保证每次生成的文档结构一致。
占位符命名我习惯用中文加双花括号，比如{{错误码表}}。英文占位符也用过，{{error_codes}}这种，但团队里非技术同事看着费劲，后来统一改成中文了。占位符对应的内容我一般先在Notion或者飞书文档里填好，再整段拷进ChatGPT。这样比在对话框里现填更稳，也不容易漏字段。
模板文件我按接口类型分了几份。查询类接口一份，创建类一份，更新类一份，删除类一份。查询类的模板响应参数表占位符多，创建类的请求体字段表占位符多。分开放的好处是用的时候不用删删改改，直接挑对应的模板填变量就行。我团队里新来的同事一开始嫌模板多，用了一周之后自己也开始按类型存模板了。模板这东西，前期花十分钟整理，后面每次省五分钟，划算。
还有个细节，模板里我留了一行{{特殊说明}}占位符，默认是空的。遇到有特殊逻辑的接口，比如“该接口有频率限制，每分钟最多10次”，就往这行里填一句。没有特殊逻辑就空着，模型也不会多问。这个占位符是我后来加的，之前遇到特殊接口总得临时在对话框里补话，容易漏。现在统一走模板，生成前扫一眼有没有特殊说明要填，漏的概率低多了。
模板和占位符搭好了，接下来就是跑工作流。下一章我聊怎么把生成、校验、迭代串成一条线，以及怎么判断生成出来的文档能不能直接用。
4. 提示词驱动的API文档生成工作流与质量评估
上一章结尾我说了要聊生成、校验、迭代怎么串成一条线，还有怎么判断文档能不能直接用。这一章就把这条线拉出来。我自己跑这套流程跑了小半年，中间踩过不少坑，有些环节刚开始根本没当回事，后来发现少了它整条线就断。
4.1 接口信息收集与需求准备
信息收集这一步，我最开始是直接从产品经理的需求文档里扒接口描述。扒了两周就发现不行。需求文档是写给开发看的，字段说明经常就一句"用户状态"，类型、枚举值、单位全得靠猜。猜错了生成出来的文档比不写还坑，前端照着接完发现字段传错格式，回头还得返工。后来我改成三头对接：产品给业务语义，后端给技术细节，我自己补读者视角的说明。三方信息在飞书表格里并成一张接口信息卡，每个接口一张卡，字段名、类型、必填、枚举值、单位、边界条件全列清楚。
需求准备里有个容易被忽略的活儿是确认读者。同样是用户查询接口，写给前端对接的文档要重点讲请求参数格式和响应字段含义，写给第三方合作方的文档得多写鉴权和限流说明。我有一次偷懒，直接拿内部文档改了个抬头就发给外部合作方，结果对方来信问"Bearer token从哪拿"，我才意识到鉴权流程得单独写一段。那之后我每份文档生成前都会在提示词里把读者写死，不给自己留含糊的余地。
收集的内容我习惯存两份。一份是结构化的参数表，直接喂进提示词；一份是零散的备注，比如"这个接口偶尔会超时，建议客户端设3秒超时重试"，这类信息放在表格里不合适，就挂到{{特殊说明}}占位符下面。两份东西分开存的好处是，参数表改起来干净利落，备注随便加不影响结构。
4.2 生成、校验与迭代优化流程
生成初稿我一般选在信息卡填完的当天做，隔太久再回来补，当时跟后端确认过的细节就忘得差不多了。初稿出来的第一眼我不看内容，先扫结构。章节顺序对不对，参数表列名齐不齐，代码块有没有包对语言。结构对了再看内容，结构不对直接回炉，省得在错的结构上修修补补。
校验我手里有一张清单，是踩坑踩出来的。字段表跟信息卡逐行对，漏一个标一个；示例值跟字段说明对，单位不符的揪出来；错误码跟错误码表对，多出来的删掉，少了的补上；请求示例里的鉴权头、路径参数、查询参数，一个不落地过一遍。这张清单刚开始写的时候只有五行，现在长到十几行，每行背后都是一次返工。校验时间大概占整个流程的一半，听起来多，但比文档发出去被人挑错再改要省事。
迭代我给自己定了个规矩：最多改三轮。第一轮改结构性问题，第二轮改字段说明和示例值，第三轮只动措辞。三轮改完还有大毛病，说明问题出在信息卡上，不在提示词上，回源头补信息比在对话框里死磕管用。我试过跟ChatGPT耗到第七轮，越改越乱，前面定好的约束被它悄悄丢了两条。现在三轮定稿，定不了就重新收集信息再跑一遍，反而快。定稿之后我会把最终版文档和当时用的提示词一起存档，下次遇到类似接口，改改变量就能复用，连迭代过程都能省掉。
4.3 文档完整性、一致性与准确性评估
完整性我主要看接口覆盖率和字段覆盖率。接口覆盖率是手头所有接口里有多少份生成了文档，这个好数。字段覆盖率麻烦一点，得拿信息卡跟文档逐字段比对。我一开始只数文档里写了几个字段，没跟源数据对，结果有一份文档把三个响应字段合并成一段话写了，看着挺全，实际拆不出来。后来改成逐字段打勾，漏一个补一个，覆盖率才算真实。
一致性这块我吃过亏。同一个项目的三份文档，一份参数表列名叫"是否必填"，一份叫"必填"，还有一份写"required"，前端同事吐槽说看三份文档要切换三次脑子。那之后我在提示词模板里把参数表列名写死成"字段名、类型、必填、说明、示例值"，所有接口统一走这个格式。枚举值的写法也统一，一律写成"0-正常，1-禁用，2-注销"，不用"0表示正常"这种散文句式。一致性这东西单看一份文档感觉不出来，攒到十几份放一起，差别就刺眼了。
准确性是最难量化的。类型写没写错、必填标没标对、单位是不是分、时间戳是不是秒，这些都得跟后端确认。我的做法是抽检加重点核对。抽检每批文档随机挑三份全字段过一遍，重点核对是拿最近改过接口定义的那几个接口单独对。有一次抽检发现一个金额字段文档里写的是"元"，实际接口传的是"分"，差了整整一百倍。那份文档已经发出去两天了，幸亏前端还没开始接。从那以后金额、时间、ID这类容易出错的字段，我生成完会专门搜一遍，确认单位和格式。
评估结果我不打分，只记问题类型和数量。每批文档生成完记一笔：漏字段几个、示例值问题几个、格式不统一几处。攒够五批回头看一次，哪类问题反复出现，就回提示词里加一条约束。这个方法笨，但管用。我现在的示例值问题已经从每批七八个降到一两个了。
4.4 版本管理与团队协作机制
文档版本我跟着接口版本走，接口路径里带v1，文档文件名就带v1。接口升到v2，文档另存一份v2，不覆盖旧的。这个规矩是吃过亏才立的。有次后端悄悄改了一个响应字段的类型，我从字符串改成数字没注意，直接覆盖了原文档，结果还在用老接口的客户端照着新文档对接，报了类型错误。那之后旧版本文档一律只归档不删除，文件头加一行"该版本已废弃，请使用v2"。
文档本身我放Git仓库里管，跟代码放一块儿。好处是变更记录自动留痕，谁改的、改了什么、什么时候改的，翻提交历史就行。提示词文件也一起放进去，跟文档同目录，命名对应上。这样别人拿到一份文档，能顺藤摸瓜找到生成它的提示词，想复现或者改一版都方便。团队里新同事入职，我让他先翻两周的文档和提示词提交记录，比讲半天流程管用。
团队协作上我们分了两条线。写提示词的和校验文档的不是同一个人，写的人容易对自己写的约束有盲区，换双眼睛看能揪出不少问题。每周五下午抽半小时过一遍这周生成的文档，谁写的谁讲两句，其他人挑毛病。这个会刚开始没人愿意开，觉得浪费时间。开了几次之后大家发现，同一类错误在不同人身上反复出现，集中聊一次能同时改好几个人的模板。现在这会成了固定动作，比单独改提示词效率高。
版本升级的时候我会多做一步：把新旧两版文档丢给ChatGPT让它列差异。人工对比两份几十行的参数表容易眼花，模型列出来的变更点我再逐条核对，快很多。核对完的差异清单附在版本说明里，前端和后端对接的时候直接看清单，不用通读全文。这个小动作省下来的沟通时间，比我写提示词的时间还多。
5. 进阶应用、常见问题与最佳实践
前四章聊的都是主干道上的事：提示词怎么搭、模板怎么设计、工作流怎么串、质量怎么评。这一章说点边角料。边角料听着不重要，真跑起来，多语言示例、OpenAPI 联动、失效排查、脱敏合规这几块，哪一块没处理好都能把前面攒的成果拖下水。我把这半年攒下来的东西摊开讲。
5.1 多语言与多框架API文档生成
我们团队的技术栈比较杂。后端主力是 Java 的 Spring Boot，网关用 Go 写的 Gin，数据组有几个 Python 脚本要调接口，前端那边还用 Node 写了个 BFF 层。同一个用户查询接口，我得给四种语言各出一份调用示例。刚开始我图省事，在提示词末尾加一句“请同时生成 Java 和 Python 示例”，出来的东西没法看。Java 代码里混着 Python 的缩进风格，@RequestParam 和 requests.get 挤在同一段代码块里，谁看了都得骂人。
后来改成每个语言单独跑一遍。提示词里把语言、框架、HTTP 客户端库、甚至库的版本号都写死。Spring Boot 那份就明确写“使用 Spring Web 的 @RestController 和 @RequestParam 注解，不要用 WebFlux 的写法”。Gin 那份写“使用 gin.Context 的 ShouldBindQuery 绑定查询参数”。框架差异这块我做了个小片段库，把每个框架的注解风格和参数绑定方式各存一段，生成时按框架把对应片段贴进提示词开头。这招省了不少来回解释的口舌。
有一个坑我印象很深。Python 示例我默认写了 requests，项目里实际用的是 httpx 的异步客户端。生成完没人细看，一个同事直接抄进脚本，跑起来才发现调用方式是同步的，卡了半分钟。从那以后依赖库的名字和版本必须出现在提示词里，不能靠模型默认。多语言不只是代码翻译。术语也得统一。中文文档里注释写中文，给海外团队看的那份写英文，两边分开控制。我在提示词开头放了一张小术语表，“分页”统一叫分页参数，不让人一会儿写 pagination 一会儿写 page query。
5.2 与OpenAPI、Swagger等规范结合
手写 OpenAPI 的 YAML 是最折磨人的活。几十个接口的 paths 和 components 手敲，缩进错一格整份文件校验失败，报错还指不到具体行。我试过让 ChatGPT 直接从接口信息卡生成 OpenAPI 3.0 片段，效果比我预期好不少。提示词里有几个点必须写清楚：规范版本写 3.0.3，输出纯 YAML 不要任何解释性文字，schema 用 $ref 引用 components 里的定义，公共响应结构抽出来复用。这四条写进约束之后，生成出来的片段基本能直接进 Swagger Editor 跑校验。
踩过的坑集中在两处。模型喜欢在 example 字段里塞中文说明，比如 example: 用户ID，整数，YAML 解析器直接报错。缩进它也爱混着两个空格和四个空格来。我的处理办法是生成完立刻丢进 Swagger Editor 或者用 openapi-generator 校验一次，报错信息原样贴回对话框让它修，比人眼去找缩进快得多。还有个更省事的做法，在提示词里贴一段已有的规范文件当风格锚点，告诉它“按这个格式输出”，稳定性明显上升。
接口改版的时候我不用模型从零重写整份 YAML。把现有的 YAML 片段贴进去，让它只输出需要变更的那几个路径和 schema，diff 我自己合。从零重写它会把没改的接口重新编一遍，字段名和顺序都可能漂移，合起来比重写还费劲。增量更新这个思路用在文档正文上也一样，改一段生成一段，别让它重写全文。
5.3 常见提示词失效原因与排查方法
失效的表现就那么几种：输出少了字段、字段凭空编造、格式跑偏、前面定好的约束被忘掉。原因我归成三类。输入太长被截断，这是最常见的。一份接口信息卡加上几十行历史对话，超出上下文窗口，模型只看得见后半截，前半截的禁制令全白写。第二类是约束过载，一次塞二三十条要求进去，它记得住前五条，后面的全丢。第三类是信息本身有歧义，信息卡里写“状态：0/1/2”没写含义，它就开始自己编，编出个“0-启用，1-禁用”，跟实际定义正好反了。
排查顺序我是固定的。先看结构，章节顺序对不对、参数表列名齐不齐、代码块有没有包对语言。结构错了直接重跑，不在错的结构上修。结构对了再数字段个数，跟信息卡逐行比对。字段数对上了才逐字段核对类型、必填、枚举值、单位。这三步走完，问题基本都能定位到具体是输入的问题还是模型的问题。
约束过载这事我调整过好几轮。现在是硬约束分两拨，最前面放五条最关键的，末尾再重复三到五条，中间放软性的风格要求。模型对首尾的注意力确实比中间强。temperature 调到 0.2 左右，格式漂移少很多。遇到反复失效的提示词，我会换个模型跑一遍做对照，能排除掉模型本身的问题。给提示词末尾加一段自检要求也挺有用：让它输出正文前先列一遍字段清单，漏字段的概率能降下来一截。信息卡里的枚举值和单位必须是写全的，这一块省下的功夫，后面都得用返工补回来。
5.4 安全合规与提示词治理
脱敏这事我犯过错。有次调试接口，顺手把带测试环境 token 的请求示例整段贴进对话框，事后想起来出了一身冷汗。测试环境的权限虽然有限，这种做法本身就不该有。现在所有示例统一用占位符：{{ACCESS_TOKEN}}、{{USER_ID}}、{{TIMESTAMP}}。真实域名、内网 IP、数据库连接串、员工邮箱一律不进提示词。共享提示词库里加了个正则扫描，提交前自动扫一遍，命中敏感词直接拦下来。
合规边界也得说清楚。生成的文档里不能出现内部系统拓扑，不能把未公开的接口名写进去。给外部合作方的文档单独走一遍审核，只保留对外开放的鉴权和限流说明，错误码也只写对外那一部分。内部文档和外部文档我用两套提示词，开头就把读者身份写死，不共用，省得哪天手滑把内部那份发出去看。接口的废弃状态、数据保留策略、个人信息字段，这些在提示词里都要单独标出来，不能靠模型自己判断哪些能写哪些不能写。
提示词本身现在是团队资产，得管起来。我们放 Git 里，每个提示词文件头写清楚适用场景、维护人、上次验证日期。改动要走一次评审，谁改的、为什么改、改完跑了哪几个接口做验证，都记在提交信息里。提示词和它生成的文档放在同一个仓库，命名对应上，别人拿到文档能顺着找到源头。新同事入职我让他先翻两周的提示词提交记录，比口头讲流程管用得多。
5.5 最佳实践清单与落地建议
清单我列在下面，都是踩过坑之后留下的：
- 信息卡先行。字段名、类型、必填、枚举值、单位、边界条件全部填齐再动提示词，缺一项后面都得返工。
- 读者身份写死在提示词开头。前端对接、第三方合作、内部存档，三种读者三套写法。
- 硬约束放首尾，软约束放中间。数量控制在十条以内，多了记不住。
- 三轮定稿。第一轮改结构，第二轮改字段和示例，第三轮只动措辞。三轮还不行就回信息卡找问题。
- 结构先于内容。先看章节顺序和参数表列名，结构不对直接重跑。
- 示例值必须可核。金额、时间戳、ID 这类字段生成完单独搜一遍，确认单位和格式跟接口定义一致。
- 统一格式锚点。参数表列名、枚举值写法、时间格式，一份项目里只允许一种。
- 提示词和文档同仓管理，命名对应，变更留痕。
- 每批文档记一笔问题类型和数量，攒够五批复盘一次，哪类问题反复出现就回提示词加约束。
- 脱敏前置。占位符写进模板，敏感词扫描挂在提交钩子上，别靠自觉。
落地建议我只说一条：别一上来全铺开。挑一个接口量中等、团队配合度高的项目先试点，跑两周，把遇到的问题按类型记下来。试点期的目标不是产出多少份文档，是把提示词模板和校验清单磨顺。这两样东西顺了，往别的项目推只是改改变量的事。反过来，模板没磨好就全团队推广，每个人都按自己的理解改一版，三个月后你会发现仓库里有十七个版本的提示词，谁也不知道哪个是对的。
